場景

開發一個項目需要前端和後端的配合，而接口文檔則是連接前後端的一個橋樑。接口文檔一般由後端驅動完成，當然也可以由前端驅動完成。只要文檔一出來，兩邊都可以同時開幹，提高開發效率。你是不是還在煩惱要用什麼雲文檔平臺來編寫接口說明，完全不需要，因爲Postman已經爲我們提供了在線文檔發佈功能。下面，我將告訴大家如何在Postman上預覽併發布文檔。

在此之前，你最好創建一個Postman帳號並登錄，因爲之後的章節所介紹的功能都可能要先登錄。

實戰

首先創建一個集合(collection)，因爲集合是文檔生成的最小單位。如有需要，可以加上描述，介紹一下這個集合是對應哪一個工程/業務。
在該集合裏創建一個請求(request)，我們繼續複用之前用過的簡單GET請求。添加一些必要的註釋，例如params、headers、body等。
爲該請求添加示例(example)。示例其實很好理解，一般好的接口文檔都有成功請求的示例，以及失敗時的示例，大家主要關注請求的返回值(response)。一對請求值和返回值合起來才能算一個示例。點擊Examples(0)的Add Example添加示例，我們添加一個請求成功的示例。我們在NAME填入成功作爲示例名稱，在Status填入成功時返回的HTTP狀態碼，一般爲200 OK，並在返回值RESPONSE中填入成功時返回的數據。
如果接口已經開發完，則不需要造一個返回結果。我們可以點一下Send發送請求得到真實的返回值，點一下返回值附近的Save按鈕，把當前的請求值和返回值作爲一個示例保存下來，填入示例名字即可。
重複第2和第3步，把所有請求及對應示例和註釋都寫好，就可以在線預覽文檔。點擊集合右邊的三角形，再點View in web，在web中打開該集合。在頁面中，我們可以很直觀的看到我們最終發佈的文檔的樣子，左邊是文件夾和接口列表，中間頂部是集合介紹，下面是每個接口的請求地址、方法、參數和描述等，最右邊是對應的示例。
當然，現在別人是看不到的，因爲你還沒發佈出去。我們可以點頁面右上角的Publish按鈕來發布該文檔，也可以直接在Postman桌面客戶端的集合右鍵選擇Publish Docs發佈。在發佈設置頁面中，記住請勿勾選Collection discover，不然你的文檔就會暴露在Postman社區上，你懂的。發佈之後就會得到一個地址，可以分享給與你協同的其他開發者，不需要密碼訪問（當然也設置不了密碼）。已發佈的文檔可以隨時修改保存或下架的。
其他人打開之後可以通過頁面右上角的Run in Postman把所有請求一鍵導入到自己的Postman桌面客戶端（前提是你電腦已經安裝最新版Postman，貌似chrome插件版享受不到這項功能）。