今天主題

在前面的章節裡我們學會了透過Collection來管理大量的API，輔以各種環境變數的幫助，日益完善的工作區讓我們可以應對各種情境。但有時可能真的過太久了，即使保有Postman設定，難免會遇到忘記如何使用的情況，需要重新花費時間回憶並熟悉，更不用說當團隊協作需要把設定共享給其他人時，學習成本就會成倍增加。

因此Documentation對於管理API來說就如同程式語言需要註解一樣，好的文件可以讓使用API的人了解它的作用以及它是如何工作的。幸運的是我們不需要另外編寫文件，可以直接在Postman提供的編輯器上進行文件撰寫，搭配Tests、Visualization的幫助，文件不會只有文字，可以實際透過測項理解API的作用。

今天的挑戰就是要自選API來為它添加文件，盡可能從各種角度去幫助使用的人了解請求的細節，那麼在開始之前，記得先把Day 20: Documentation複製到自己的工作區。

回到自己的工作區，打開今天的資料夾Documentation，可以從右方我們每天都很依賴的文件區看到今天挑戰的指引，主要是要自選一個API，然後為其添加文件，自由發揮但需要包含一些項目

• 請求描述裡面至少要有一個指向官方文件的超連結
• 如果有參數或標頭，要提供說明
• 把一個成功的回應結果儲存成example

這邊我選擇了Pokémon API，以下是步驟

• 新增請求: 在今天的資料夾Documentation下新增

  • 取名 pokemon
  • 方法 GET
  • URL https://pokeapi.co/api/v2/pokemon

• 編輯文件: Postman可以用Markdown語法來撰寫文件，所以先簡單填入

  用途: 取得指定數量的pokemon
  
  > 官方文件: [Doc]([https://pokeapi.co/docs/v2](https://pokeapi.co/docs/v2))
  

• 新增參數與變數:

  • 新增兩個Collection Variables, {{LIMIT}} 及 {{OFFSET}}
  • 讓參數分別使用兩個變數，並添加說明

  

  新增參數後，原本的文件下方Query Params也會隨之自動更新

  

• 新增測試: 有時測試項目本身就像是文件一樣的存在，透過測項能夠讓我們理解輸入輸出之間的關係，甚至透過前面提過的Visualization方法可以讓使用API的人通過圖形化的結果，更容易理解API的用途。

  pm.test("Status code is 200", function () {
      pm.response.to.have.status(200);
  });
  
  pm.test("Check limit", function () {
      let results = pm.response.json().results
      let limit = Number(pm.collectionVariables.get("LIMIT"));
  
      pm.expect(results.length).to.equal(limit);
  });
  
  
  var template = `
      <table bgcolor="#FFFFFF">
          <tr>
              <th>Name</th>
              <th>URL</th>
          </tr>
  
          {{#each response}}
              <tr>
                  <td>{{name}}</td>
                  <td>{{url}}</td>
              </tr>
          {{/each}}
      </table>
  `;
  
  // Set visualizer
  pm.visualizer.set(template, {
      // Pass the response body parsed as JSON as `data`
      response: pm.response.json().results
  });
  

• 新增範例: 試著Send，然後將成功的回應另存成example

• submit: 跟著上面步驟做的話，測試可以不用加，基本上就能滿足今天挑戰的內容了，按下submit如果有測項失誤的話，就再自己進行調整囉。

今日回顧

文件對於API管理來說真的是很重要，如果還沒有感覺的話，其實可以再去看看之前介紹過的Postman API，看看是否能不通過閱讀它的文件就能理解API如何使用。今天我們也實際體驗了如何透過Documentation、Description、Tests等等機制來輔助使用API的人，不過目前為止還只是剛入門，畢竟文件的格式是另一門學問，每個團隊有自己適合的文件格式。

今日延伸閱讀:
Documenting your API

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