使用 Postman 發(fā)布接口

1. 前言

你可以自動生成 Postman API 文檔，可以私下分享文檔，或者在 web 上發(fā)布文檔。Postman 基于集合生成和托管文檔，實時同步并可以通過瀏覽器訪問。你可以使用該文檔與團隊成員或合作伙伴協(xié)作。

2. 生成文檔

文檔都是基于集合的，所以你可以為一個已存在的集合創(chuàng)建文檔，也可以將文檔依賴于某個集合。

2.1 給已存在的集合創(chuàng)建文檔

要在 Postman 給一個已存在的集合創(chuàng)建文檔，先選擇集合，然后點擊圖中向右箭頭的按鈕：

然后點擊“在 web 查看 (view in web)”就可以在 web 打開文檔：

Tips：你可以在 Postman 或者 web 上直接更改文檔。

另外一種創(chuàng)建文檔的方式是，點擊 New -> API Documentation -> Select an existing collection -> 選擇集合：

3. 發(fā)布文檔

你可以發(fā)布 API 文檔對公眾可見，這樣，任何擁有該鏈接的人都可以查看它。發(fā)布的文檔讓大家了解怎么使用你的 API 以及 API 的詳細信息，包括參數(shù)，請求和響應體和示例代碼；

你的文檔是實時更新的根據(jù)你集合的狀態(tài)，所以你不用每次都重復發(fā)布流程去更新你的文檔。

文檔中包含一個“在 Postman運行 (Run in Postman)”按鈕用戶就可以直接在 Postman 中運行該 API。例如， 請參考 Postman API 文檔。 將你的文檔添加到 API網(wǎng)絡和模板中也可以讓你的集合在 Postman 中可用，例如幫助開發(fā)者接受和采用。

3.1 發(fā)布文檔的方法

右鍵點擊集合( collections )，然后點擊發(fā)布文檔（Publish Docs）：

發(fā)布成功之后，瀏覽器上會有一個 URL， 通過這個 URL 你就可以看到這個集合的 API 文檔，真的很簡單：

Tips：環(huán)境中人和機密信息(e.g. 密碼和訪問令牌)都可能在發(fā)布文檔時公開可見，所以在發(fā)布文檔之前要確保環(huán)境中不包含任何機密信息

3.2 定制化文檔

Tips：你可以選擇為你發(fā)布的文檔選擇一個域名。

你可以為你的 API 文檔配置背景色，代碼背景和高亮顏色。還可以為你的文檔選擇默認布局，比如單列或者雙列視圖。當然你還可以更改和預覽這些設置會在發(fā)布時如何顯示。

3.3 分享文檔

要把文檔分享給你的用戶或者其他 Postman 社區(qū)中的人，那么請開啟集合可查“Collection discovery”功能。這能讓你的文檔通過 Postman API 網(wǎng)絡和模板變得可查可用。

Tips：當你把文檔公開發(fā)布之后，任何拿到 URL 的人都可以訪問。

• 選擇添加到 API 網(wǎng)絡( Add to API Network) 讓你的文檔在 Postman 發(fā)布網(wǎng)絡中可查可用；
• 選擇添加到 Postman 模板( Add to Postman Templates) 可以把你的集合分享到 Postman 社區(qū)

4. 查看文檔

你可以查看分享給你的任何集合的文檔。擁有查看權限的 Postman 團隊、業(yè)務和企業(yè)成員可以查看和評論文檔；擁有編輯權限的這些成員可以修改和更新文檔。

當你通過點擊在網(wǎng)頁查看( View in web) 打開 API 文檔：

打開之后，在頂部可以看到一些配置選項，可以選擇環(huán)境( environment ), 布局( layout )：

還能看到每個請求的詳細信息，包括示例代碼，要求的授權類型， URL， 描述，請求和響應結構。

5. 小結

API 生成之后，重點還是在于怎么去查看和應用；這篇文章主要講述 API 文檔的定制、發(fā)布和分享，以及如何查看其他人分享的文檔。