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。 它们在内部和外部使用者中也更易于维护，更易于使用。
如果没有适用于 API 的 OpenAPI 规范，可以使用开发代理从截获的请求和响应生成一个。
