OpenAPI:让API的定义规范起来

OpenAPI:让API的定义规范起来

Tags
API设计
DSL设计
Schema设计
CreatedTime
Aug 19, 2022 02:32 AM
Slug
2021-06-10-openapi
UpdatedTime
Last updated August 19, 2022

什么是OpenAPI?

openapi是用于定义API信息的规范。抽象了info、path、request、header、response等元信息(见官方文档),定义的约束文件是json-schema(见官方文档),生成的api信息是json配置文件(见GUI系统)。
除了此规范外,还有其它规范用于定义API,比如Google、Github都有自己的API规范。相较来说,swagger openapi 更通用,适用性更广。

OpenAPI的用途是什么?

  1. 规范了API元信息的格式,用于描述API输入、输出、请求头、作者、版本等信息
  1. 因为有了规范,可以快速的生成API文档
  1. API是服务间「沟通数据」的基础,统一的规范能极大提高开发效率,降低连接成本

V3.0版本有什么新特性?

OpenAPI计划在一年多前发布了3.0版本。它包括一些非常酷但仍未充分利用的功能。最重要的是,它扩展了描述API的能力。很高兴看到OpenAPI在后续版本中加强了这一能力。3.0版还引入了两个很酷的新元数据:LINKS和CALLBACKS。

LINKS(链接)

通常,API调用的结果可以用作另一个API调用的输入。您甚至可能已经在其响应主体中看到了包含文字链接的API。
OpenAPI的链接功能添加了描述不同API之间链接的静态元数据,以及如何使用一个API的输出作为另一个API的输入。很高兴看到更多的OpenAPI文档使用链接和更好的工具来指定链接。

CALLBACKS(回调)

注册webhook时,通常会将URL作为字符串传入,然后该服务将调用该API。OpenAPI 3.0允许您描述回调的签名以及它应该具有的参数。再者,这非常有助于让开发人员脱离文档并通过代码发现问题。
notion image

OpenAPI的不足体现在哪?

这里以搭建一个中间层接口编排系统(BFFP)为例(以阿里云的「编排系统」为例)。
基于openAPI,可以直接使用其规范好的request、verson、response等metadata结构,并将其运用在API的定义上。经过长时间的发展完善,OpenAPI中的抽象概念覆盖面非常广,不需要自己再去想这些元信息。
不足之处:
  • BFFP需要支持读取代码,但是openAPI没有直接支持读取代码的元信息。
  • OpenAPI 缺少hooks的定义(v3版本新增了callback定义,但是只能用在接口执行完之后,不支持接口的其它生命周期)
  • OpenAPI对编排能力有缺失(v3版本新增了links定义,只能满足数据的传递转换,相当于pipe管道;但是满足不了复杂编排的定义)

参考链接

2、openapi 3.0-更智能的API: https://zhuanlan.zhihu.com/p/73689422