使用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 提供了一些思路，下面简单介绍。

合规性校验

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

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

1. 下载代码： https://github.com/NewCapec-Institute/oas-validator clone
2. 而后 mvn clean install 打包
3. 到 oas-validator-web/target 目录下执行 java -jar oas-validator-web-exec.jar 启动 OAS Validator Web
4. 访问 http://localhost:8080，进入合规性校验功能
5. 把 petstore.yaml 内容贴到文本框中而后点击校验获得结果：

$.tags : 至少提供一个
$.openapi : 必须>=3.0.2
$.components.schemas.'Pet'.title : 必须提供
$.components.schemas.'Pet'.properties.'id'.title : 必须提供
$.components.schemas.'Pet'.properties.'name'.title : 必须提供
$.components.schemas.'Pet'.properties.'tag'.title : 必须提供
$.components.schemas.'Error'.title : 必须提供
$.components.schemas.'Error'.properties.'code'.title : 必须提供
$.components.schemas.'Error'.properties.'message'.title : 必须提供
$.info.description : 必须提供
$.paths./pets.get.tags[0] : 不在$.tags所定义的范围内
$.paths./pets.get.responses.200.headers.'x-next' : 必须为upper hyphen case
$.paths./pets.post.tags[0] : 不在$.tags所定义的范围内
$.paths./pets/{petId}.get.tags[0] : 不在$.tags所定义的范围内

下面是功能截图：

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

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

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

再来看这一条报告 $.paths./pets.get.responses.200.headers.'x-next' : 必须为upper hyphen case，一样前面是JsonPath，告诉你该属性应该为Upper Hyphen Case，正确的写法应该是X-Next。和title属性同样Header的大小写不是一个技术问题，可是统一的大小写风格可以让下游应用的开发人员更温馨，从而有更少的Bug。

兼容性校验

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

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

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

openapi: "3.0.0"
info:
  version: 1.0
  title: Swagger Petstore
paths:
  /pets/{petId}:
    get:
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

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

openapi: "3.0.0"
info:
  version: 1.1
  title: Swagger Petstore
paths:
  /pets/{petId}:
    get:
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

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

$.paths./pets/{petId}.get.parameters[1].required : [name=name,in=query]:仅容许新增required=false的parameter

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

总结

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

目前OAS Validator已捐赠给Servicecomb Toolkit，同时已整合到Servicecomb Toolkit项目中提供服务，但愿可以为广大开发者带来帮助。

最后，欢迎开发者朋友们加入ServiceComb社区，一块儿作些有意思的事情。加入ServiceComb社区

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

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

2019年度最受欢迎中国开源软件

投票啦！

小伙伴们，2019最受欢迎中国开源软件评选开始啦！

请帮忙给

【开发框架、库类】的Apache ServiceComb

以及  

Go Chassis

投票吧！

【投票方式】

一、点【2019年度最受欢迎中国开源软件】进入页面投票

（每人能够投5票）

组织须要你的一臂之力

请给予咱们支持和反馈

咱们会继续努力

为你们提供更好用的开源软件服务

爱大家！