OpenAPI 规范（以前称为 Swagger）描述了 API 的各个方面。 OpenAPI 规范（规范）描述了 API 的终结点、参数和响应。 OpenAPI 规范以 YAML 或 JSON 编写，由工具用来生成文档、测试用例和客户端库。 通过拥有 OpenAPI 规范，API 开发者可以确保其 API 得到准确描述、更易于访问且更易于跨各种应用程序和服务集成。
下面是应考虑为 API 使用 OpenAPI 规范的原因：
- 以标准化方式记录 API。 以一致且可读的格式记录 API 规范。
- 生成客户端 SDK。 使用 Kiota 等工具以各种编程语言自动生成客户端库。
- 创建模拟 API。 根据 API 规范创建模拟服务器，这有助于在尚未实现实际 API 的早期阶段进行开发。
- 改进协作。 提供不同的团队（前端、后端、QA），并清楚地了解 API 的功能和限制，这有助于新团队成员快速赶上。
- 简化测试和验证。 根据规范自动验证 API 请求和响应，从而更轻松地识别差异。
- 与 API 管理工具集成。 使用许多 API 管理工具和网关（例如 Azure API 中心和 Azure API管理）轻松集成、部署和监视 API。
- 简化 API 网关配置。 使用 OpenAPI 规范配置 API 网关并自动执行路由、转换和跨域资源共享设置等任务。
通过使用 OpenAPI 规范，可以创建设计良好且文档保持一致的 API。 它们也更易于维护，并且更便于内部和外部使用者使用。
还没有 OpenAPI 规范？
为已存在的 API 手动编写规范需要一些时间，并且会逐渐偏离 API 的实际行为。 另一个选项是记录 API 返回的内容并从中生成规范。
| Approach | 您将获得的内容 | 需要关注的内容 |
|---|---|---|
| 手写 | 可完全控制说明和示例 | 它需要时间，并且会偏离实际 API |
| 从代码注释生成它 | 与代码保持同步的规范 | 你需要访问 API 的代码，并且框架必须支持它 |
| 从已记录的流量中生成 | 你可以调用的任何 API 的规范，包括你不拥有的 API | 它仅涵盖你记录的请求，因此请调用你需要的 API 部分 |
Dev Proxy 记录应用和 API 之间的请求和响应，并从中生成 OpenAPI 规范。 有关步骤，请参阅 生成 OpenAPI 规范。
