OpenAPI 和 Swagger 基础
OpenAPI 是接口描述规范，Swagger 是围绕这套规范的一组工具生态。很多人口头上还会说“写 Swagger 文档”，但更准确地说，是编写或生成 OpenAPI 文档，再用 Swagger UI、Swagger Editor 等工具查看和调试。
1. OpenAPI 和 Swagger 的关系
2015 年，Swagger 规范捐赠给 Linux Foundation，后来改名为 OpenAPI。规范改名了，但 Swagger 这个工具品牌保留下来。
可以这样区分：
- OpenAPI：标准和规范，定义接口怎么描述。
- Swagger：工具生态，用来编辑、展示、生成和调试 OpenAPI 文档。
所以“Swagger 文档”和“OpenAPI 文档”在很多语境下指的是同一类东西。
2. Code-First 和 Design-First
API 文档有两种主流工作流。
2.1 Code-First
Code-First 是代码优先。先写后端代码，再通过注解、注释或框架插件生成 OpenAPI 文档。
优点：
- 开发快。
- 不需要手写大量 YAML。
- 文档更容易跟代码保持同步。
缺点：
- 业务代码里容易混入大量注解。
- 文档结构可能不够干净。
- 复杂多态结构描述起来比较别扭。
适合内部小项目、单体应用、MVP 和快速迭代项目。
2.2 Design-First
Design-First 是设计优先。先写 OpenAPI YAML 或 JSON，评审通过后再生成服务端桩代码、客户端 SDK 或 Mock Server。
优点：
- 接口契约清晰。
- 前后端可以并行。
- 跨语言、跨团队协作更稳定。
缺点：
- 前期投入更大。
- 需要维护 OpenAPI 文件。
- 对团队规范要求更高。
适合微服务架构、对外公开 API、大团队协作和强契约场景。
3. Mock Server
Mock Server 可以根据 OpenAPI 文档生成一个假的接口服务。后端还没实现时，前端可以先对着 Mock 数据联调页面。
它的价值在于把“接口有没有定下来”和“后端有没有写完”分开。只要契约稳定，前端、测试、客户端 SDK 都可以提前工作。
4. 文档不同步的问题
API 文档最大的坑是和代码不同步。接口逻辑改了，OpenAPI 文档没改，文档就成了僵尸文档。
解决方式通常有两类：
- Code-First：由代码自动生成文档，减少人工同步成本。
- Design-First：在 CI 中检查文档变更，接口变更必须先改契约。
无论哪种方式，都要把文档同步放进开发流程，而不是靠开发者记忆。
5. 谁会使用 OpenAPI
OpenAPI 不只是给后端看的。
| 角色 | 用途 |
|---|---|
| 后端 | 编写、生成和校验接口文档 |
| 前端 | 查看字段、联调接口、生成类型 |
| 测试 | 做接口测试、Mock、契约校验 |
| 产品 | 验收接口逻辑和数据结构 |
| 外部开发者 | 阅读 API 文档、生成 SDK |
6. 生产环境注意事项
Swagger UI 很方便，但生产环境要谨慎暴露。如果任何人猜到 URL 就能看到所有接口，甚至直接发起调试请求，就会增加攻击面。
常见做法：
- 生产环境禁用 Swagger UI。
- 或者加登录鉴权和 IP 白名单。
- 对外 API 只暴露经过整理的公开文档。
接口文档是协作工具，不应该变成生产环境的未授权入口。