使用OAS Validator帮助你规范OpenAPI Spec文档

作者 | 钱嘉

来源 | 微服务蜂巢公众号

当前主流的开发 RESTful API 的做法有两种：Code First 和 Contract First。Code First 指先写代码，然后生成 Contract，而 Contract First 则是先写 Contract 再写代码实现。

两种做法各有利弊，Code First 可以让开发人员先写接口实现，然后利用工具反向生成 Contract，优点是快速开发，并能保证接口实现与 Contract 保证一致，缺点是 Contract 太过易变容易导致下游应用故障。Contract First 则可以让 Contract 的变动受控，保证下游应用的稳定性，缺点是需要人工来保证接口实现与 Contact 的一致性，具有一定难度。

对于如何规范管理 Contract，新开普软件研究院开源的 OAS Validator[1] 提供了一些思路，下面简单介绍。

合规性校验

OAS Validator 支持对使用 OpenAPI V3[2] 编写的 Contract 文档做合规性校验（也可称之为风格校验）。

在一个微服务架构的系统中，提供 RESTful API 的组件可能会有很多个，并且由不同开发人员 / 团队开发，那么在使用这些接口的时候有一个很自然的需求就是希望这些接口（或接口文档）的风格是一致的。OAS Validator 的合规性校验做的就是这部分工作。下面举例说明怎么使用合规性校验功能：

下载代码：https://github.com/NewCapec-Institute/oas-validator clone

然后 mvn clean install 打包

到 oas-validator-web/target 目录下执行 java -jar oas-validator-web-exec.jar 启动 OAS Validator Web

访问 http://localhost:8080，进入合规性校验功能

把 petstore.yaml 内容贴到文本框中然后点击校验得到结果：

下面是功能截图：

下面举例解释检查报告的意思：

$.components.schemas.'Pet'.title : 必须提供，前面一段是 JsonPath[3]，用来描述出问题的元素 / 属性的位置，“必须提供”则的意思是没有填写该属性。如下图：

title 是一个文档性字段，没有它虽然不影响接口的语义，但是对于下游应用的开发者来说没有它会造成理解上的困难，因此在这里我们把它设定为必填。

兼容性校验

不管你是采用 Code First 还是 Contract First，Contract 的变动不可避免，那么如何保证变化后的 Contract 能够对下游应用向下兼容就成了不可回避的问题。这个问题的具体描述就是根据 V1.0 Contract 开发的下游应用是否依然能够与根据 V1.1 Contract 实现的接口正确交互。

OAS Validator 提供了这种兼容性校验，当然同样只支持 OpenAPI V3 文档。下面举例说明如何使用这一功能：

我们先提供一个 v1.0 的 OAS Spec：

再写一个 v1.1 的 OAS Spec，添加了一个 query 参数 name：

然后同样打开 OAS Validator Web，进入“兼容性校验”功能，在左侧贴上 v1.0 在右侧贴上 v1.1，点击校验得到结果：

这个报告的意思是新增的 query 参数 name 是必填的，这种做法不向下兼容。仔细想想是不是的确如此？

总结

关于 OAS Validator 的详细文档可见 Github。需要注意的是，目前校验规则还不能配置，但是在代码层面提供了接口供扩展，你可以根据自己的需求写一个自己的合规性校验器。

目前 OAS Validator 已捐赠给 Servicecomb Toolkit[4]，同时已整合到 Servicecomb Toolkit 项目中提供服务，希望能够为广大开发者带来帮助。

最后，欢迎开发者朋友们加入 ServiceComb 社区，一起做些有意思的事情。加入社区方法 [5]

如果文章对您有帮助，欢迎小伙伴收藏 toolkit 项目，为项目加 Star~

https://github.com/apache/servicecomb-toolkit

参考资料：

[1] OAS Validator

https://github.com/NewCapec-Institute/oas-validator

[2] OpenAPI V3

https://github.com/OAI/OpenAPI-Specification

[3]JsonPath

https://github.com/json-path/JsonPath

[4] Servicecomb Toolkit

https://github.com/apache/servicecomb-toolkit

[5] 加入 Servicecomb 社区

http://servicecomb.incubator.apache.org/cn/docs/join_the_community/