OpenAPI Specification 2.0 (Swagger 2.0) 完整指南：API 描述、验证与代码生成

openapi-specification-v2 by hairyf/skills

360 周安装量

8 GitHub Stars

安装命令

npx skills add https://github.com/hairyf/skills --skill openapi-specification-v2

🇨🇳中文介绍

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

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

核心参考

主题	描述	参考链接
格式与结构	文档格式、文件结构、数据类型	core-format-and-structure
固定与模式化字段	模式中的固定字段名与模式化字段名	core-fixed-patterned-fields
Swagger 对象	根文档、必需/可选字段、扩展	core-swagger-object
信息与元数据	Info、Contact、License 对象	core-info-metadata

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

776,000 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

261,300 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

210,800 周安装

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

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

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

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

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

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

2026 年 1 月 30 日

🇺🇸English

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.

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

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

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

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

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

Best Practices

Topic	Description	Reference
Spec Authoring	operationId, tags, responses, parameters, definitions, security	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

Weekly Installs

345

Repository

hairyf/skills

GitHub Stars

First Seen

Jan 30, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

cursor337

claude-code315

codex78

gemini-cli77

opencode77

github-copilot75

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

140,500 周安装

OpenAPI Specification 2.0 (Swagger 2.0) 完整指南：API 描述、验证与代码生成

🇨🇳中文介绍

核心参考

相关 Skills

路径与操作

参数与响应

模式与定义

安全性

最佳实践

高级主题