openapi-specification-v2

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAPI Specification 2.0 (formerly Swagger 2.0) defines a JSON/YAML format for describing RESTful APIs: paths, operations, parameters, responses, schemas, and security. Use this skill when creating or editing Swagger 2.0 specs, validating structure, or generating code/documentation from them.

The skill is based on OpenAPI Specification 2.0, generated at 2026-01-30.

OpenAPI Specification 2.0（前身为Swagger 2.0）定义了一种JSON/YAML格式，用于描述RESTful API：包括路径、操作、参数、响应、模式和安全等内容。当你创建或编辑Swagger 2.0规范、验证结构，或者从中生成代码/文档时，可以使用本技能。

本技能基于OpenAPI Specification 2.0，生成时间为2026-01-30。

Core References

核心参考

Topic	Description	Reference
Format and Structure	Document format, file structure, data types	core-format-and-structure
Fixed and Patterned Fields	Fixed vs patterned field names in the schema	core-fixed-patterned-fields
Swagger Object	Root document, required/optional fields, extensions	core-swagger-object
Info and Metadata	Info, Contact, License objects	core-info-metadata
Tags and External Docs	Tag Object, External Documentation Object	core-tags-and-external-docs
Reference Object	$ref, JSON Pointer, same-document and external file references	core-reference-object
Data Types and Formats	Primitives, format table, validation, file type	core-data-types-and-formats
MIME Types	consumes/produces, RFC 6838, examples	core-mime-types
HTTP Status Codes	Response keys, default response, IANA/RFC 7231	core-http-status-codes
Path Templating	Curly braces, path parameters, name matching	core-path-templating
Header Object	Response header definition (type, format, items, validation)	core-header-object
Headers Object	Container for response headers (name → Header Object)	core-headers-object
Items Object	Non-body array items (parameters, headers)	core-items-object
Example Object	Response examples by MIME type	core-example-object

主题	描述	参考链接
格式与结构	文档格式、文件结构、数据类型	core-format-and-structure
固定与模式化字段	模式中的固定字段与模式化字段名称	core-fixed-patterned-fields
Swagger对象	根文档、必填/可选字段、扩展	core-swagger-object
信息与元数据	Info、Contact、License对象	core-info-metadata
标签与外部文档	Tag对象、外部文档对象	core-tags-and-external-docs
引用对象	$ref、JSON指针、同文档与外部文件引用	core-reference-object
数据类型与格式	基本类型、格式表、验证、文件类型	core-data-types-and-formats
MIME类型	consumes/produces、RFC 6838、示例	core-mime-types
HTTP状态码	响应键、默认响应、IANA/RFC 7231	core-http-status-codes
路径模板	大括号、路径参数、名称匹配	core-path-templating
头对象	响应头定义（类型、格式、项、验证）	core-header-object
头集合对象	响应头容器（名称 → 头对象）	core-headers-object
项对象	非主体数组项（参数、头）	core-items-object
示例对象	按MIME类型分类的响应示例	core-example-object

Paths and Operations

路径与操作

Topic	Description	Reference
Paths and Operations	Paths Object, Path Item, Operation Object	paths-and-operations
Path Item $ref	External path definition, conflict behavior	path-item-ref

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

Parameters and Responses

参数与响应

Topic	Description	Reference
Parameters	Parameter locations (path, query, header, body, formData)	parameters
collectionFormat	csv, ssv, tsv, pipes, multi and where they apply	parameters-collection-format
Parameters Definitions (Reuse)	Root-level parameters, reuse via $ref	parameters-definitions-reuse
Responses	Responses Object, Response Object	responses
Responses Definitions (Reuse)	Root-level responses, reuse via $ref	responses-definitions-reuse

主题	描述	参考链接
参数	参数位置（路径、查询、头、主体、formData）	parameters
collectionFormat	csv、ssv、tsv、pipes、multi及其适用场景	parameters-collection-format
参数定义（复用）	根级参数、通过$ref复用	parameters-definitions-reuse
响应	Responses对象、响应对象	responses
响应定义（复用）	根级响应、通过$ref复用	responses-definitions-reuse

Schemas and Definitions

模式与定义

Topic	Description	Reference
Schema and Definitions	Schema Object, Definitions, composition, polymorphism	schema-and-definitions
Schema JSON Schema Keywords	JSON Schema Draft 4 subset and Swagger-specific fields	schema-json-schema-keywords

主题	描述	参考链接
模式与定义	Schema对象、定义、组合、多态	schema-and-definitions
模式JSON Schema关键字	JSON Schema Draft 4子集与Swagger特定字段	schema-json-schema-keywords

Security

安全

Topic	Description	Reference
Security	Security Definitions, Security Scheme	security
Security Requirement Object	Applying security at root/operation, OR/AND logic	security-requirement-object
Scopes Object	OAuth2 scope name → description	security-scopes-object
Basic and API Key	basic and apiKey Security Scheme	security-basic-apikey
OAuth2 Flows	implicit, password, application, accessCode and required URLs	security-oauth2-flows

主题	描述	参考链接
安全	安全定义、安全方案	security
安全需求对象	在根/操作级别应用安全、OR/AND逻辑	security-requirement-object
作用域对象	OAuth2作用域名称 → 描述	security-scopes-object
基础认证与API密钥	basic和apiKey安全方案	security-basic-apikey
OAuth2流程	implicit、password、application、accessCode及所需URL	security-oauth2-flows

Best Practices

最佳实践

Topic	Description	Reference
Spec Authoring	operationId, tags, responses, parameters, definitions, security	best-practices-spec-authoring

主题	描述	参考链接
规范编写	operationId、标签、响应、参数、定义、安全	best-practices-spec-authoring

Advanced

高级内容

Topic	Description	Reference
Vendor Extensions	x- prefix, value types, where allowed	advanced-vendor-extensions
Security Filtering	Empty Paths, empty Path Item for access control	advanced-security-filtering
Extensions and XML	XML Object for schema properties	advanced-extensions-and-xml

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