使用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票）

組織須要你的一臂之力

請給予咱們支持和反饋

咱們會繼續努力

爲你們提供更好用的開源軟件服務

愛大家！