OpenAPI

OpenAPI 规范（原 Swagger 规范）是由 OpenAPI Initiative 维护的业界标准，用于描述 HTTP API 的接口定义。该规范采用厂商中立、可移植的方式提供 API 的技术元数据，使得人类和机器都能理解 API 的功能、请求参数、响应结构等核心信息。官网作为社区中心，提供最新规范文档、工具集成说明、教育培训资源以及参与贡献的指南。

核心内容与功能

• OpenAPI 规范：当前最新版本为 3.1.x，支持完整的 REST API 描述，包括路径、操作、参数、请求体、响应、安全方案等。
• Arazzo 规范：用于描述 API 调用序列和工作流的规范，补充单体 API 描述能力。
• Overlay 规范：允许在不改变原始规范的情况下，叠加额外元数据或修改。
• 社区资源：包含 GitHub 参与指南、Slack 交流群、技术指导委员会（TSC）会议记录、博客和案例分享。
• 教育培训：提供免费的 OpenAPI 基础培训课程，帮助开发者快速上手。

适用人群

• 后端开发者：通过规范定义 API 接口，自动生成文档和 SDK。
• API 产品经理与设计师：利用标准化描述进行 API 规划、协作和评审。
• 测试工程师：基于规范生成测试用例，进行自动化验证。
• 技术文档写作者：从规范中提取信息生成交互式文档。

使用方式

访问官网可在线阅读规范全文（PDF/HTML），下载 YAML 或 JSON 格式的规范文件。开发者可通过社区工具（如 Swagger UI、Swagger Codegen、Redoc 等）解析规范并生成交互式文档或客户端代码。若想参与贡献，可加入 Slack 社区或直接向 GitHub 仓库提交 issue/PR。

注意事项

OpenAPI 规范专注于 HTTP API 描述，不涵盖消息队列、GraphQL 等其他协议。使用时应遵循语义化版本控制，避免未迁移至新版规范导致兼容性问题。社区工具与规范版本需匹配，部分旧工具可能不支持最新特性。