openapi-specification-v2

OpenAPI Specification 2.0（原 Swagger 2.0）定义了一种 JSON/YAML 格式，用于描述 RESTful API：路径、操作、参数、响应、Schema 和安全性。在创建或编辑 Swagger 2.0 规范、验证结构，或基于它们生成代码/文档时，请使用此技能。

该技能基于 OpenAPI Specification 2.0，生成于 2026-01-30。

核心参考

主题	描述	参考
格式与结构	文档格式、文件结构、数据类型	core-format-and-structure
固定字段与模式化字段	Schema 中的固定字段名与模式化字段名	core-fixed-patterned-fields
Swagger Object	根文档、必需/可选字段、扩展	core-swagger-object
Info 与元数据	Info、Contact、License 对象	core-info-metadata
Tags 与外部文档	Tag Object、External Documentation Object	core-tags-and-external-docs
Reference Object	$ref、JSON Pointer、同文档引用与外部文件引用	core-reference-object
数据类型与格式	基本类型、格式表、验证、file 类型	core-data-types-and-formats
MIME 类型	consumes/produces、RFC 6838、示例	core-mime-types
HTTP 状态码	响应键、默认响应、IANA/RFC 7231	core-http-status-codes
路径模板化	花括号、路径参数、名称匹配	core-path-templating
Header Object	响应头定义（type、format、items、验证）	core-header-object
Headers Object	响应头的容器（名称 → Header Object）	core-headers-object
Items Object	非 body 数组项（参数、请求头）	core-items-object
Example Object	按 MIME 类型提供的响应示例	core-example-object

路径与操作

主题	描述	参考
路径与操作	Paths Object、Path Item、Operation Object	paths-and-operations
Path Item $ref	外部路径定义、冲突行为	path-item-ref

参数与响应

主题	描述	参考
参数	参数位置（path、query、header、body、formData）	parameters
collectionFormat	csv、ssv、tsv、pipes、multi 及各自的适用场景	parameters-collection-format
Parameters Definitions（复用）	根级参数，通过 $ref 复用	parameters-definitions-reuse
响应	Responses Object、Response Object	responses
Responses Definitions（复用）	根级响应，通过 $ref 复用	responses-definitions-reuse

Schema 与 Definitions

主题	描述	参考
Schema 与 Definitions	Schema Object、Definitions、组合、多态	schema-and-definitions
Schema JSON Schema 关键字	JSON Schema Draft 4 子集与 Swagger 专有字段	schema-json-schema-keywords

安全性

主题	描述	参考
安全性	安全定义、安全方案	security
安全需求对象	在根/操作级别应用安全性，OR/AND 逻辑	security-requirement-object
作用域对象	OAuth2 作用域名称 → 描述	security-scopes-object
Basic 和 API Key	basic 和 apiKey 安全方案	security-basic-apikey
OAuth2 流程	implicit、password、application、accessCode 及必需的 URL	security-oauth2-flows

最佳实践

主题	描述	参考
规范编写	operationId、tags、responses、parameters、definitions、security	best-practices-spec-authoring

进阶

主题	描述	参考
供应商扩展	x- 前缀、值类型、允许使用的位置	advanced-vendor-extensions
安全过滤	空 Paths、用于访问控制的空 Path Item	advanced-security-filtering
扩展与 XML	用于 schema 属性的 XML 对象	advanced-extensions-and-xml