最近，微软宣布在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

创作场景

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