前情提要

在前面的挑戰中，我們曾經體驗過Mock Serivces，可以在前後端討論出介面之後，根據規格開始各自的工作。那麼問題來，怎樣的介面才能讓前後端都能夠理解呢?

OpenAPI規範就很適合用來描述Restful API的介面，它透過json或是yaml格式來描述API能做什麼事以及如何去使用，優點就是不需要綁定程式語言，任何人都可以從這份規格讀懂它並完成實作。另外OpenAPI也因為有著既定格式與規範，所以機器也能讀懂，因此發展出了許多工具能產生文件，甚至產生部分的程式碼實作。

今日主題

今天的主題是關於如何透過Postman的API builder來載入OpenAPI定義好的規格，從而自動建構相關的API、Collection、Documentation以及Example。在開始今天挑戰前，記得把 Day 18: API specifications 複製到自己的工作區。

回到自己工作區後，打開今天資料夾API specifications，右方的文件有今天任務的提示，也可以直接按照下列步驟來操作:

• 載入yaml: 點擊左上方Import，會跳出下面視窗，讓我們透過
  https://raw.githubusercontent.com/postmanlabs/spectral-postman/master/cosmos2.yaml這個連結來進行載入

  

  下一步保持選項打勾就可以進行下一步，這樣將會在我們的工作區自動新增一個Collection

  

• 檢查載入結果
  載入後可以到APIs頁面的Definition觀看載入的結果，會發現當前載入的yaml檔案有需要修正的地方，下方的視窗也有顯示具體錯誤的原因

  
  這是因為Cosmos預期回傳一個陣列，所以需要定義items，而縮排後下面每一個item都是一個個Cosmo，調整如下，存檔後可以發現錯誤已被修正

      Cosmos:
        type: array
        items:
          required:
            - id
            - name
          properties:
            id:
              type: integer
              format: int64
            name:
              type: string
            tag:
              type: string
  

• 驗證元素: 由於前面有修改Definitions，因此接著要如下圖，在Collection Documentation頁面右上找到Validate against Documentation，點擊後開始驗證像是mock、monitor、collection等元素

  

  驗證完會發現之前產生的Collection已經跟先前定義的不一樣了，所以會列出有更動的部分，這邊就全選並點擊Confirm Changes to Collection就可以了

  

• 試發API: 回到工作區Collections分頁可以看到有新增的Collection Cosmos，分別試發兩個API，沒意外的話第二個API會回傳錯誤訊息，只要更改Params裡的cosmoId值就可以了

• submit: 到這邊就可以嘗試submit來測試今天挑戰是否成功，但今天有兩個submit請求，第一個跟之前的差不多，只要把Cosmos的Collection id填入變數值即可，第二個需要填入今天載入的API id，可以在下圖的地方找到它

  

今日回顧

今天嘗試了用Postman去載入OpenAPI定義的API規格，大致上能夠理解統一規範的優點，但要真的能夠運用到實務上，還需要花費好些時間把OpenAPI的規範試過一遍，想要推廣到團隊也是需要經過分享或教學等時間成本，不過至少目前至少體驗過留下了印象，等到時機到，自然就可能繼續深耕了。

• API development overview

那麼今天就到這邊，我們明天見~