使用 Postman 發(fā)布接口

1. 前言

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

2. 生成文檔

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

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

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

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

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

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

3. 發(fā)布文檔

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

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

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

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

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

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

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

3.2 定制化文檔

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

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

3.3 分享文檔

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

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

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

4. 查看文檔

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

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

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

還能看到每個(gè)請(qǐng)求的詳細(xì)信息，包括示例代碼，要求的授權(quán)類型， URL， 描述，請(qǐng)求和響應(yīng)結(jié)構(gòu)。

5. 小結(jié)

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