微软宣布在 Azure API 管理中预览 OpenAPI 规范 V3

最近，微软宣布在 Azure API 管理中支持 OpenAPI 规范 V3，他们的服务允许创建、发布、监控和维护 API。OpenAPI 规范的使用是通过 OpenAPI .NET SDK 完成的，并支持从它们的实现中抽象出 API 定义。

OpenAPI 规范（以前称为 Swagger）提供了以独立于语言的方式描述 RESTful Web 服务的方法。随着 OpenAPI 的广泛采用，已经形成了一个多样化的生态系统，我们可以使用各种 工具 来设计、记录、构建、测试和实现治理。该规范受 Linux 基金会下属的 OpenAPI Initiative 监督，并有各种各样的组织推动其开发，包括 SmartBear、微软和 WSO2 等公司。任何人都可以在 OpenAPI Initiative 的 GitHub 存储库上跟踪甚至参与规范的开发。

根据微软 Azure MVP 和 Azure 架构师 Tom Kerkhove 的说法，在向消费者公开 API 时，规范扮演着重要的角色。

API 必须干净整洁且文档良好。这让你的消费者可以知道你提供了哪些功能、它们的用途以及可以有怎样的期望。这就是 OpenAPI 规范（又名 Swagger）的作用所在，它定义了应该如何在整个行业中定义 API，而不管其背后的技术是什么。

规范的版本 3 带来了一些变化，现在 Azure API 管理也已经支持这些变化。例如，这个新版本引入了一个包含诸如消息头、链接和回调等组件的全新体系结构，在定义中采用了更加模块化的方法，RestCase 首席执行官 Guy Levin 对此进行了描述。

3.0 版本的 API 规范格式采用一种更加模块化且可重用的方法定义 API 表面（surface area），提供了更强大的请求和响应模型描述能力和灵活性，并详细描述了构成 API 用法的通用组件，如底层数据模式和安全定义。

引入的另一个选项是在操作中包含 callbacks，这意味着现在可以定义 webhook。最后，链接（linking）使我们可以定义 API 的不同路径之间的关系，提供了属性扩展能力。

随着公告发布，现在已经可以在 Azure API 管理中导入 OpenAPI V3 定义，尽管有一些限制。目前，既可以通过门户，也可以通过 REST API。接着，导出 OpenAPI 描述的功能也已经可用，可以通过开发者门户，或使用另一个 REST API 调用。

最终，这些功能将正式发布，使用 PowerShell SDK 进行定义的导入和导出也会成为可能。

查看英文原文：

https://www.infoq.com/news/2019/01/openapi-v3-support-azure-apim