CNDBA社区
OpenAPI 3.0 规范的 Swagger 文档，通常指的是遵循 OpenAPI Specification (OAS) 3.0 版本标准编写的 API 接口描述文档。
这个术语的使用源于历史原因，需要澄清以下几点：
OpenAPI 与 Swagger 的关系：
- Swagger 最初是一个由 SmartBear 公司开发的开源框架，用于设计、构建、文档化和使用 RESTful API。它有一套自己的规范。
- 2015年，SmartBear 将 Swagger 规范捐赠给了 OpenAPI Initiative (OAI) 组织。
- 在 OAI 的管理下，该规范被重命名为 OpenAPI Specification (OAS)。
- 因此，Swagger 是 OpenAPI 的前身。现在，“OpenAPI”是官方的、标准化的名称。
为什么还叫 “Swagger 文档”？
- 历史惯性： “Swagger” 这个名字在开发者社区中根深蒂固，即使规范已经更名为 OpenAPI，人们仍然习惯性地用 “Swagger” 来指代 API 文档。
- 工具链： 许多流行的工具仍然以 “Swagger” 命名，例如：
- Swagger UI： 一个非常流行的开源工具，可以将 OpenAPI 3.0 规范的 JSON 或 YAML 文件渲染成一个美观、交互式的网页文档。
- Swagger Editor： 一个在线编辑器，用于编写和验证 OpenAPI 规范。
- Swagger Codegen： 可以根据 OpenAPI 规范生成客户端 SDK 或服务端骨架代码。
- 所以，当人们说“给我 Swagger 文档”时，他们通常指的是“给我一个 OpenAPI 3.0 规范的文件，最好能用 Swagger UI 查看”。
OpenAPI 3.0 规范的核心内容：
一个符合 OpenAPI 3.0 规范的文档（通常是一个.yaml或.json文件）会详细描述你的 API，包括：- 基本信息： API 的标题、版本、描述、服务器地址等。
- 路径 (Paths)： API 的所有端点（如
/users,/products/{id}）。 - 操作 (Operations)： 每个端点支持的 HTTP 方法（GET, POST, PUT, DELETE 等）。
- 参数 (Parameters)： 请求中可以接受的参数（路径参数、查询参数、请求头等），包括名称、类型、是否必需等。
- 请求体 (Request Body)： 对于 POST、PUT 等操作，描述请求体的数据结构（通常引用
components/schemas中定义的模型）。 - 响应 (Responses)： 描述每个操作可能返回的 HTTP 状态码（如 200, 404, 500）以及对应的响应体结构。
- 数据模型 (Schemas)： 在
components/schemas部分定义 API 中使用的复杂数据对象的结构（类似于 JSON Schema）。 - 安全方案 (Security)： 描述 API 的认证和授权机制（如 API Key, OAuth2, Bearer Token 等）。
- 其他： 如回调、链接、服务器变量等高级特性。
总结来说：
当你听到“OpenAPI 3.0规范的Swagger文档”时，它指的是：
- 一个遵循 OpenAPI 3.0 标准编写的 API 描述文件。
- 这个文件通常可以用 Swagger UI 等工具渲染成一个漂亮的、可交互的网页。
- 虽然名字里有 “Swagger”，但其技术标准是 OpenAPI 3.0。
你可以把它理解为：一份用 OpenAPI 3.0 语言写的 API 合同，而 “Swagger” 是查看这份合同最常用的浏览器。
