讓你的 Postman 更專業 — Mock Server & Environments & Publish API doc

Postman 除了 api 的基礎驗證外，還有許多加速工作效率的功能，這篇文章你將學會建立 Mock Server，從此不再苦苦等待後端 api；如果你曾經為了測試正式機/測試機/本機而開了一大堆只有網址不同的 request，了解如何設定 Environments 將大幅精簡 Postman 的 request 數量；常常被夥伴抱怨 api 參數問題嗎？Postman 內建的 API doc 讓合作夥伴獲得跟你一樣的環境來使用這些 api！

一、建立 Mock Servers
  🤔 為什麼需要學習這個技術？
  STEP 1：建立 Mock Server
  STEP 2：設計 Mock Server response
二、設定 Environments
  🤔 如果不了解怎麼設定會發生什麼蠢事？
  STEP 1：新增 Environments
  STEP 2：設定常用的 Environments variable
  STEP 3：在 request 使用 Environments variable
三、匯出 API documentation
  🤔 為什麼同事常常說我正確的api有問題？
  STEP 1：view documentation
  STEP 2：publish documentation
四、補充說明
  🤫 讓 Mock server 變成私有的

一、建立 Mock Server

🤔 為什麼需要學習這個技術？

過去在前後端分離的架構下，在 api 規格開出來後前端需等待後端完成 api 後才能做後續的開發；為了不讓前端在這段時間偷懶😏，Mock server 應運而生！他能回傳假資料供前端使用，等後端完成 api 後他只需要切換 end point 就能使用真實資料。

除了上面的原因外，如果你開發環境的 api sever 不太穩定常常因不明原因工作異常，Mock server 也能保證你的工作效率不受影響，畢竟不可能每次都等到 Server 修好後在工作吧？

STEP 1：建立 Mock Server

Postman 改版非常快速，你看到的畫面可能跟我有些許不同

如果不是選擇已經存在的 api Collection ，需要至少填寫一個 Request URL 讓Collections 有初始化的 api Request

給 Mock server 取個名字，並建議你勾選儲存 Mock server URL 到環境變數的選項。

建立成功後便可以在『Mock Servers』的分頁中看到剛剛建立的 Server，點進去後能看到這個 Sever 的網址

因為剛剛有儲存 Mock server URL 到環境變數，我們到『Environments』的分頁做個確認

STEP 2：設計 Mock Server response

在『Collections』的分頁我們能找到剛剛初始化的 request， {{url}} 會帶入環境變數所以右上角請選擇剛剛建立的『Mock_User』，按下『Send』後你會發現下面的 response 一片空白，這是因為我們還沒設定 Mock Server response。

你可以看到 request 下面有一個『Default』，他就是用來填寫假資料的 example，下面我們用 JSON 格式寫個簡單的 response 範例後按『Save』

再回到剛剛的 request 按下『Send』就發現會回應剛剛寫的 response 呢！

除了自動產生的 Default 外，我們還可以自己新增其他的 example

可以透過加入 Params 讓這個 request 有不同的 response，這裡我們新增『error』、『correct』這兩個來做示範

在 Params 填寫的 DESCRIPTION 日後會顯示在 api 文件上，如果可以也請盡量寫清楚

回到剛剛的 request ，我們將 control_res 加入『Params』，依據 VALUE 的不同按下『Send』就會看到對應的 response 嚕～

二、設定 Environments

🤔 如果不了解怎麼設定會發生什麼蠢事？

有沒有覺得上面這張圖片看起來很蠢😅，在了解 Environments 怎麼設定前，我的 Collections 就是這麼的複雜😇，因為寫程式時通常環境會有：『本機、開發機、測試機、正式機』，如果每新增一個環境你就複製一份，到最後你會無法進行妥善管理；更何況大多數的 api 其實只有網址的差異而已。

STEP 1：新增 Environments

之前在建立 Mock Server 時其實就已經用到了 Environments，這裡我在詳細的跟大家說這個東西的好處

到『Environments』的分頁按下『＋』的按鈕，接著輸入環境的名稱即可(我用 local_server 做示範)

STEP 2：設定常用的 Environments variable

url：這個是最實用的環境變數，讓你只需要調整 request 的 Environment 就快速切換網址做測試

login_user、login_password：每個環境的使用者登入資訊通常略有不同，且大部分的 api 都需要透過登入取得 token 才能使用，把他們加入環境變數可以加速你的測試。

P.S 不建議把正式機的 password 加入環境變數，且測試機的 password 不要用平常自己會用的密碼，不然資安很危險的，都已經可以偷懶用 Environments，密碼自己去產生一組吧。

STEP 3：在 request 使用 Environments variable

想在 request 中使用 Environments variable 只需要用 {{your_env_var}} 包起來就好，另外右上角記得要切換到正確的 Environments 才會帶入相應的資料喔！

三、匯出 API documentation

🤔 為什麼同事常常說我正確的api有問題？

相信後端工程師有一個共同經驗，無論你的 API 文件寫得再清楚功能執行的再穩定；到了同事手中卻常常被說不能 work，緊張的你檢查很多遍也找不出問題，百思不得其解的抵達同事座位才發現他原來漏了某個參數。

如果你有這樣的經驗，Postman 內建的 API documentation 能拯救你，讓你在 publish 文件後可以跟同事幸福快樂的生活。

STEP 1：view documentation

選擇想要產生文檔的 Collection，按下『view documentation』就會顯示在右側，同時你可以透過切換右上角的環境變數來檢視文檔。

STEP 2：publish documentation

當你確定文檔內容都沒問題後按『Publish』

接著會跳出一個網頁讓你調整一些參數，調整完後建議先用左側的『Preview Documentation』自己確認看看是否符合

確認一切都沒問題後按下『Publish Collection』就發布出去嚕～

你可以將 URL 複製起來分享給你的合作夥伴，如果你想把這份文檔下架，按『Unpublish』即可

四、補充說明

🤫 讓 Mock server 變成私有的

在前面 Mock Server 時不知道有沒有人注意到有『Make mock server private』的選項，這做這個設定前這個 mock server 的 url 都是公開的，如果你想為自己的 mock server 多一層防護可以這樣做

STEP 1 : 編輯 Mock server

從『Mock Servers』分頁打開之前創建的 Server，按下『Edit』做設定

將『Make mock server private』打勾並按下『Save changes』

回到之前的 Request，你會發現按下 Send 後會回傳錯誤訊息，這是因為現在 Mock server 都需要添加 api key 到 request 的 header 才能使用

STEP 2 : 產生 Postman API key

進去這個 網址 ，點擊『Generate API key』

填上用來識別這個 API key 的名稱後按下『Generate API key』

接著請複製這個 API key，上面已經警告你這是你唯一見到他的機會了

STEP 3：將 API key 加入 Environment

因為日後 Mock server 的所有 request 都需要這個 API key，所以我們把他加入 Environment，變數名稱為『x-api-key』

STEP 4：request 的 header 加上 x-api-key

最後回到 request，在 Headers 的分頁下加入『x-api-key』這個參數並將環境變數 {{x-api-key}} 作為值後按下『Send』就看到正確的 response 回傳嚕！