Swagger 简介
Swagger 的来历、从 2.0 到 OpenAPI 3.x 的演进，以及它在接口全生命周期里的位置。
Key PointsSwagger 2.0 是旧规范名，2015 年捐给 OpenAPI Initiative 后改叫 OpenAPI，3.0 起支持 oneOf/anyOf、多服务器与更完整的请求体描述。
来历
Tony Tam created Swagger in 2010 while documenting Wordnik's API. In 2015 SmartBear donated the specification to the OpenAPI Initiative under the Linux Foundation; the spec became the OpenAPI Specification while Swagger remained the tooling brand.
版本演进
| Version | Year | Highlights |
|---|---|---|
| Swagger 1.x | 2011 | JSON only, minimal structure |
| Swagger 2.0 | 2014 | Single file, definitions, widely supported |
| OpenAPI 3.0 | 2017 | components, requestBody, oneOf/anyOf, multiple servers |
| OpenAPI 3.1 | 2021 | Full JSON Schema 2020-12 alignment, webhooks |
在接口生命周期里的位置
- 设计先行 — 先定
openapi.yaml，前后端并行开发 - Mock — 由规范直接生成假数据服务，前端不必等后端
- 实现 — 服务端按规范实现，或用代码注解生成规范
- 测试 — 用规范做契约测试，防止实现漂移
- 发布 — Swagger UI / Redoc 渲染成对外文档
和其他文档方式的对比
| Approach | Stays in sync | Try it | Codegen |
|---|---|---|---|
| Markdown / Wiki | No | No | No |
| Comments in code | Partly | No | No |
| OpenAPI spec | Yes, it is the source | Yes | Yes |
来历
2010 年 Tony Tam 为 Wordnik 的 API 做文档，写出了 Swagger 规范与 Swagger UI。2015 年 SmartBear 把规范捐给 Linux 基金会下的 OpenAPI Initiative，规范更名为 OpenAPI Specification，Swagger 则保留为工具品牌。
版本演进
| 版本 | 年份 | 主要变化 |
|---|---|---|
| Swagger 1.x | 2011 | 仅 JSON，结构简单 |
| Swagger 2.0 | 2014 | 单文件、definitions，支持最广 |
| OpenAPI 3.0 | 2017 | components、requestBody、oneOf/anyOf、多服务器 |
| OpenAPI 3.1 | 2021 | 对齐 JSON Schema 2020-12，支持 webhooks |
在接口生命周期里的位置
- 设计先行 —— 先定
openapi.yaml，前后端并行开发 - Mock —— 由规范直接生成假数据服务，前端不必等后端
- 实现 —— 服务端按规范实现，或用代码注解生成规范
- 测试 — 用规范做契约测试，防止实现漂移
- 发布 —— Swagger UI / Redoc 渲染成对外文档
和其他文档方式的对比
| 方式 | 是否易同步 | 可调试 | 可生成代码 |
|---|---|---|---|
| Markdown / Wiki | 否 | 否 | 否 |
| 代码注释 | 部分 | 否 | 否 |
| OpenAPI 规范 | 是，它就是源头 | 是 | 是 |