iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 19
0
Software Development

30天開發與部署 Laravel 專案系列 第 19

Postman:API客戶端測試與線上文件

https://ithelp.ithome.com.tw/upload/images/20201003/20125263obJhBMSKQZ.png

Postman官網可看到它具備以下功能

  • API Client :模擬client送出request
  • Automated Testing:CI/CD
  • Design & Mock :模擬response
  • Documentation:提供線上文件
  • Monitors:監控API狀況
  • Workspaces:共享與協作

本系列文章有提到API測試驗證採用Postman,因此本篇分享個人使用 API Client與 Documentation的經驗。

API Client

新建立一個request時,可以看到postman呈現內容如下

https://ithelp.ithome.com.tw/upload/images/20201004/20125263xTi8uQJhla.png

基本設定

untitle request

如題,表示未針對這個此request命名。
按下save按鈕時會強制命名與分類。

http method : GET

postman支援以下http method ,但RESTful架構下以get,post,put,delete為主
https://ithelp.ithome.com.tw/upload/images/20201004/20125263vyCEhK57tb.png

URL

網址 = URL = Domain Name + router 內的路徑
例如在本地端開發時,註冊網址就是 http://127.0.0.1:8000/api/register

params

會呈現在網址列後方的參數,明碼呈現
https://ithelp.ithome.com.tw/upload/images/20201004/201252639ehfJcEchr.png

Auth

  • 驗證token作法之一,是放在Auth裡頭,把token帶入欄位中。
  • postman支援以下幾種驗證機制,個人常用的Bearer Token,Laravel的Passport也適用此類。
    https://ithelp.ithome.com.tw/upload/images/20201004/2012526389zStPah3c.png

Header

  • 傳送body以外的資訊
  • 個人常添加的內容為
    • Content-Type:application/json
    • Accept:application/json

Body

  • 主要傳遞request內容,對應路徑與該路徑方法傳遞參數與值。
  • Postman 支援none,form-data,x-www-form-urlencode,raw,binary,GraphQL等Form content types。

環境變數設定

紀錄重複使用、或想快速切換某些參數、紀錄某個回傳值給另一個request使用...
上述功能 Postman 都可以做得到

https://ithelp.ithome.com.tw/upload/images/20201004/20125263hCF1iVb3Vc.png

首先設定環境。

  • 可透過右上角眼睛圖案右邊的按鈕,進行設定。
  • 不同環境可以快速切換

取值

  • 先確認 repsonse 的欄位跟結構。
  • 在test中透過javascript語法擷取repsonse body內容並紀錄。
    https://ithelp.ithome.com.tw/upload/images/20201004/20125263rBNqt7gC9V.png
  • 如果擷取的資料放在response header也能抓得到。

Documentation

線上API文件有許多種,例如swagger.io、Apiary等等。

Postman能一邊測試一邊彙整一套API上線文件,主要缺點就是沒辦法做版控,個人推薦原因如下

  1. 可填寫request傳送欄位範例、說明。
  2. 可建立多種成功或失敗案例。
  3. 可在描述欄位使用markdown語法,彌補response 無法註解的缺憾。
  4. 不用其他terminal指令、即時更新。

以登入為例,上圖為postman設定、下圖為postman自動產生的api文件。
https://ithelp.ithome.com.tw/upload/images/20201004/201252631qbKKHgYB8.png
設定一次就好,可以讓postman單機版或是postman線上文件的使用者同步API文件資訊。


參考資料
https://www.postman.com/
https://pjchender.github.io/2018/06/06/%E7%B6%B2%E9%9A%9B%E7%B6%B2%E8%B7%AF-%E8%AA%8D%E8%AD%98%E7%B6%B2%E5%9D%80%E8%88%87%E7%B6%B2%E5%9F%9F%E5%90%8D%E7%A8%B1%EF%BC%88domain-name-url-dns%EF%BC%89/
https://ithelp.ithome.com.tw/articles/10212102
https://stackoverflow.com/questions/26723467/postman-chrome-what-is-the-difference-between-form-data-x-www-form-urlencoded
https://swagger.io/
https://apiary.io/


上一篇
RESTful API (3):Read/Update/Delete
下一篇
apiDoc:API Document自動化套件
系列文
30天開發與部署 Laravel 專案30

尚未有邦友留言

立即登入留言