Postman 是一個接口測試和 http 請求的神器,非常好用。
官方 github 地址: https://github.com/postmanlabs
Postman 的優點:
- 支持各種的請求類型: get、post、put、patch、delete 等
- 支持在線存儲數據,通過賬號就可以進行遷移數據
- 很方便的支持請求 header 和請求參數的設置
- 支持不同的認證機制,包括 Basic Auth,Digest Auth,OAuth 1.0,OAuth 2.0 等
- 響應數據是自動按照語法格式高亮的,包括 HTML,JSON 和 XML
以下內容主要參考: Github: api_tool_postman
安裝
Postman 可以單獨作爲一個應用安裝,也可以作爲 chrome 的一個插件安裝。
-
chrome 插件安裝, Postman 插件地址
下面主要介紹下載安裝獨立版本app 軟件的 Postman 的過程:
去主頁Postman 官網找到:Postman | Apps
去下載自己平臺的版本:
- Mac
- Windows(x86/x64)
- Linux(x86/x64) 即可。
快速入門,總體使用方略
安裝成功後,打開軟件。
新建接口
對應的Request:New -> Request
或,在右邊的 Tab 頁面中點擊加號+:
即可看到新建的 Tab 頁:
設置 HTTP 請求的方法
設置 HTTP 的 Method 方法和輸入 api 的地址
設置相關請求頭信息
設置相關 GET 或 POST 等的參數
發送請求
都填寫好之後,點擊 Send 去發送請求 Request:
查看響應 Response的信息
然後可以重複上述修改 Request 的參數,點擊 Send 去發送請求的過程,以便調試到 API 接口正常工作爲止。
保存接口配置
待整個接口都調試完畢後,記得點擊 Save 去保存接口信息:
去保存當前 API 接口,然後需要填寫相關的接口信息:
- Request Name: 請求的名字
- 我一般習慣用保存爲 接口的最後的字段名,比如
http://{% raw %}{{% endraw %}{server_address}}/ucows/login/login
中的/login/login
- 我一般習慣用保存爲 接口的最後的字段名,比如
- Request Description: 接口的描述
可選
最好寫上該接口的要實現的基本功能和相關注意事項- 支持 Markdown 語法
- Select a collection or folder to save: 選擇要保存到哪個分組(或文件夾)
- 往往保存到某個 API 接口到所屬的該項目名的分組
填寫好內容,選擇好分組,再點擊保存:
此時,Tab 的右上角的黃色點(表示沒有保存)消失了,表示已保存。
且對應的分組中可以看到對應的接口了:
[warning] 默認不保存返回的 Response 數據
- 直接點擊 Save 去保存,只能保存 API 本身(的 Request 請求),不會保存 Response 的數據
- 想要保存 Response 數據,需要用後面要介紹的 多個 Example
Request 的多參數操作詳解
自動解析多個參數 Params
比如,對於一個 GET 的請求的 url 是: http://openapi.youdao.com/api?q=糾刪碼(EC)的學習&from=zh_CHS&to=EN&appKey=152e0e77723a0026&salt=4&sign=6BE15F1868019AD71C442E6399DB1FE4
對應着其實是?key=value
形式中包含多個 Http 的 GET 的 query string=query parameters
Postman 可以自動幫我們解析出對應參數,可以點擊 Params:
看到展開的多個參數:
如此就可以很方便的修改,增刪對應的參數了。
臨時禁用參數
且還支持,在不刪除某參數的情況下,如果想要暫時不傳參數,可以方便的通過不勾選的方式去實現:
批量編輯 GET 的多個參數
當然,如果想要批量的編輯參數,可以點擊右上角的Bulk Edit,去實現批量編輯。
接口描述與自動生成文檔
API 的描述中,也支持 Markdown,官方的接口說明文檔:Intro to API documentation。
所以,可以很方便的添加有條理的接口描述,尤其是參數解釋了:
描述支持 markdown 語法
而對於要解釋的參數,可以通過之前的Param -> Bulk Edit
的內容:
拷貝過來,再繼續去編輯:
以及添加更多解釋信息:
點擊 Update 後,即可保存。
發佈接口並生成 markdown 的描述文件
去發佈後:
對應的效果:有道翻譯
Response 深入
Response 數據顯示模式
Postman 對於返回的 Response 數據,支持三種顯示模式。
默認
格式化後的 Pretty 模式
- Raw 原始模式
點擊Raw,可以查看到返回的沒有格式化之前的原始數據:
- Preview 預覽模式
以及 Preview,是對應 Raw 原始格式的預覽模式:
Preview 這種模式的顯示效果,好像是對於返回的是 html 頁面這類,才比較有效果。
Response 的 Cookies
很多時候普通的 API 調用,倒是沒有 Cookie 的:
Response 的 Headers 頭信息
舉例,此處返回的是有 Headers 頭信息的:
可以從中看到服務器是 Nginx 的。
保存多個 Example
之前想要實現,讓導出的 API 文檔中能看到接口返回的 Response 數據。後來發現是Example這個功能去實現此效果的。
如何添加 Example
繼續點擊Save Example:
保存後,就能看到Example(1)了:
單個 Example 在導出的 API 文檔中的效果
然後再去導出文檔,導出文檔中的確能看到返回數據的例子:
多個 Example 在導出的 API 文檔中的效果
其他好用的功能及工具
分組 Collection
在剛開始一個項目時,爲了後續便於組織和管理,把同屬該項目的多個 API,放在一組裏
所以要先去新建一個 Collection: New -> Collection
使用了段時間後,建了多個分組的效果:
單個分組展開後的效果:
歷史記錄 History
Postman 支持 history 歷史記錄,顯示出最近使用過的 API:
用環境變量實現多服務器版本
在測試 API 期間,往往存在多種環境,對應 IP 地址(或域名也不同)
比如:
- Prod:
http://116.62.25.57/ucows
- 用於開發完成發佈到生產環境
- Dev:
http://123.206.191.125/ucows
- 用於開發期間的線上的 Development 的測試環境
- LocalTest:
http://192.168.0.140:80/ucows
- 用於開發期間配合後臺開發人員的本地局域網內的本地環境,用於聯合調試 API 接口
而在測試 API 期間,往往需要手動去修改 API 的地址:
效率比較低,且地址更換後之前地址就沒法保留了。
另外,且根據不同 IP 地址(或者域名)也不容易識別是哪套環境。
Postman 支持用 Environment 環境變量去實現多服務器版本
後來發現 Postman 中,有 Environment 和 Global Variable,用於解決這個問題,實現不同環境的管理:
很明顯,就可以用來實現不用手動修改 url 中的服務器地址,從而動態的實現,支持不同服務器環境:
- Production 生產環境
- Development 開發環境
- Local 本地局域網環境
或者:
Environments are a group of variables & values, that allow you to quickly switch the context for your requests and collections.
Learn more about environments
You can declare a variable in an environment and give it a starting value, then use it in a request by putting the variable name within curly-braces. Create an environment to get started.
輸入 Key 和 value:
點擊 Add 後:
[info] 環境變量可以使用的地方
- URL
- URL params
- Header values
- form-data/url-encoded values
- Raw body content
- Helper fields
- 寫 test 測試腳本中
- 通過 postman 的接口,獲取或設置環境變量的值。
此處把之前的在 url 中的 IP 地址(或域名)換成環境變量:
鼠標移動到環境變量上,可以動態顯示出具體的值:
再去添加另外一個開發環境:
則可添加完 2 個環境變量,表示兩個服務器地址,兩個版本:
然後就可以切換不同服務器環境了:
可以看到,同樣的變量 server_address,在切換後對應 IP 地址就變成希望的開發環境的 IP 了:
順帶也去看看,導出爲 API 文檔後,帶了這種 Environment 的變量的接口,文檔長什麼樣子:
發現是在發佈之前,需要選擇對應的環境的:
發佈後的文檔,可以看到所選環境和對應服務器的 IP 的:
當然發佈文檔後,也可以實時切換環境:
當更換服務器時,直接修改變量的 IP 地址:
即可實時更新,當鼠標移動到變量上即可看到效果:
代碼生成工具
對於當前的請求,還可以通過點擊 Code
去查看對應的符合 HTTP 協議的原始的內容:
各種語言的示例代碼Code Generation Tools
比如:
- Swift 語言
- Java 語言
- 其他各種語言 還支持其他各種語言:
目前支持的語言有:
- HTTP
- C (LibCurl)
- cURL
- C#(RestSharp)
- Go
- Java
- OK HTTP
- Unirest
- Javascript
- NodeJS
- Objective-C(NSURL)
- OCaml(Cohttp)
- PHP
- Python
- Ruby(NET::Http)
- Shell
- Swift(NSURL)
代碼生成工具的好處是:在寫調用此 API 的代碼時,就可以參考對應代碼,甚至拷貝粘貼對應代碼,即可。
測試接口
選中某個分組後,點擊 Runner
選中某個分組後點擊 Run
即可看到測試結果:
關於此功能的介紹可參考Postman 官網的git 圖
MockServer
直接參考官網。
功能界面
多 Tab 分頁
Postman 支持多 tab 頁,於此對比之前有些 API 調試工具就不支持多 Tab 頁,比如Advanced Rest Client
多 tab 的好處:
方便在一個 tab 中測試,得到結果後,複製粘貼到另外的 tab 中,繼續測試其它接口
比如此處 tab1 中,測試了獲取驗證碼接口後,拷貝手機號和驗證碼,粘貼到 tab2 中,繼續測試註冊的接口
界面查看模式
Postman 的默認的 Request 和 Response 是上下佈局:
此處點擊右下角的Two pane view
,就變成左右的了:
[info] 左右佈局的用途
對於數據量很大,又想要同時看到請求和返回的數據的時候,應該比較有用。
多顏色主題
Posman 支持兩種主題:
- 深色主題
當前是深色主題,效果很不錯:
- 淺色主題
可以切換到 淺色主題:
API 文檔生成
在服務端後臺的開發人員測試好了接口後,打算把接口的各種信息發給使用此 API 的前端的移動端人員時,往往會遇到:
要麼是用複製粘貼 -> 格式不友好 要麼是用 Postman 中截圖 -> 方便看,但是不方便獲得 API 接口和字段等文字內容 要麼是用 Postman 中導出爲 JSON -> json 文件中信息太繁雜,不利於找到所需要的信息 要麼是用文檔,比如去編寫 Markdown 文檔 -> 但後續 API 的變更需要實時同步修改文檔,也會很麻煩 這都會導致別人查看和使用 API 時很不方便。
-> 對此,Postman 提供了發佈 API
預覽和發佈 API 文檔 下面介紹 Postman 中如何預覽和發佈 API 文檔。
簡要概述步驟
- Collection
- 鼠標移動到某個 Collection,點擊 三個點
- Publish Docs
- Publish
- 得到 Public URL
- 別人打開這個 Public URL,即可查看 API 文檔
預覽 API 文檔
點擊分組右邊的大於號>
如果只是預覽,比如後臺開發員自己查看 API 文檔的話,可以選擇:View in web
等價於點擊Publish Docs去發佈:
View in Web 後,有 Publish 的選項(見後面的截圖)
View in Web 後,會打開預覽頁面:
比如:
奶牛雲
https://documenter.getpostman.com/collection/view/669382-42273840-6237-dbae-5455-26b16f45e2b9
而右邊的示例代碼,也可以從默認的 cURL 換成其他的:
發佈 API 文檔
如果想要讓其他人能看到這個文檔,則點擊 Publish:
然後會打開類似於這樣的地址:
Postman Documenter
https://documenter.getpostman.com/collection/publish?meta=Y29sbGVjdGlvbl9pZD00MjI3Mzg0MC02MjM3LWRiYWUtNTQ1NS0yNmIxNmY0NWUyYjkmb3duZXI9NjY5MzgyJmNvbGxlY3Rpb25fbmFtZT0lRTUlQTUlQjYlRTclODklOUIlRTQlQkElOTE=
點擊 Publish 後,可以生成對應的公開的網頁地址:
打開 API 接口文檔地址:
https://documenter.getpostman.com/view/669382/collection/77fd4RM
即可看到(和前面預覽一樣效果的 API 文檔了):
如此,別人即可查看對應的 API 接口文檔。
已發佈的 API 文檔支持自動更新
後續如果自己的 API 接口修改後:
比如:
(後來發現,不用再去進入此預覽和發佈的流程,去更新文檔,而是 Postman 自動支持)
別人去刷新該文檔的頁面:
https://documenter.getpostman.com/view/669382/collection/77fd4RM
即可看到更新後的內容:
參考資料
- 主要參考:Github: api_tool_postman
- Manage environments
- postman-變量/環境/過濾等 - 簡書
- Postman 使用手冊 3——環境變量 - 簡書
- postman 使用之四:切換環境和設置讀取變量 - 喬葉葉 - 博客園
作者:FlyDragon
出處:http://www.cnblogs.com/fly_dragon/
關於作者:專注於微軟平臺項目架構、管理和企業解決方案。如有問題或建議,請多多賜教!
本文版權歸作者和博客園共有,歡迎轉載,但未經作者同意必須保留此段聲明,且在文章頁面明顯位置給出原文連接,如有問題,可以通[email protected] 聯繫我,非常感謝。