最近,微软宣布在 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
评论