Postman

記錄與描述

您可以將描述添加到集合和請(qǐng)求中的各個(gè)位置，它們將出現(xiàn)在文檔中。 您可以包括集合，請(qǐng)求，參數(shù)和標(biāo)頭的描述。 您也可以直接在網(wǎng)絡(luò)上編輯您擁有編輯權(quán)限的集合中的任何文檔。

 

描述集合

您可以在文檔中包含Markdown描述，以了解集合及其中的請(qǐng)求。您可以在創(chuàng)建集合時(shí)添加說(shuō)明，也可以通過(guò)選擇集合并使用箭頭按鈕(?).來(lái)添加描述

 

 

包含塊元素時(shí)，請(qǐng)?jiān)谄淝昂罅艨招?，以避免出現(xiàn)任何渲染問(wèn)題。

當(dāng)您查看具有編輯權(quán)限的集合的文檔時(shí)，也可以在web瀏覽器中編輯描述。

 

 

記錄請(qǐng)求詳細(xì)信息

您可以在創(chuàng)建新請(qǐng)求或?yàn)楝F(xiàn)有請(qǐng)求隨時(shí)提供描述。

使用新建按鈕創(chuàng)建新請(qǐng)求時(shí)，系統(tǒng)將提示您提供名稱和描述（可以包括Markdown），這兩個(gè)名稱和描述都將出現(xiàn)在文檔中。

 

 

要將描述添加到現(xiàn)有請(qǐng)求中，請(qǐng)?jiān)赑ostman中打開(kāi)請(qǐng)求并編輯請(qǐng)求詳細(xì)信息。

 

 

說(shuō)明將出現(xiàn)在文檔的請(qǐng)求部分中。

 

 

您還可以直接從瀏覽器中的文檔中編輯請(qǐng)求的詳細(xì)信息，包括描述-可編輯的文本將在懸停時(shí)突出顯示。

 

 

單擊以編輯文本的一部分。

 

 

進(jìn)行更改，然后保存。

 

 

如果您的文檔包含任何未保存的更改，您將看到警告。

 

 

參數(shù)和標(biāo)題

您可以在請(qǐng)求中的參數(shù)和標(biāo)頭中添加說(shuō)明-適用于在Postman內(nèi)部查看請(qǐng)求的人員（例如，如果您正在共享集合中）或任何查看文檔的人員。

 

 

無(wú)論是否選中，所有鍵值對(duì)都將顯示在您的文檔中。 您可以在說(shuō)明中指出哪些是必需的，哪些是可選的。 文檔的使用者可以選擇將請(qǐng)求發(fā)送到端點(diǎn)時(shí)要使用的鍵/值對(duì)。用戶將能夠根據(jù)他們選擇的鍵值對(duì)在Postman應(yīng)用程序中生成代碼段，并且?guī)в羞@些對(duì)的URL將顯示在應(yīng)用程序中。

 

該描述將出現(xiàn)在您的文檔中的參數(shù)或標(biāo)頭名稱旁邊的請(qǐng)求參數(shù)和標(biāo)頭部分中。

 

 

授權(quán)明細(xì)

您可以在文檔中包括訪問(wèn)API所需的授權(quán)類(lèi)型。 您可以在收集級(jí)別或請(qǐng)求級(jí)別添加授權(quán)詳細(xì)信息。 在收集級(jí)別添加的授權(quán)要求適用于每個(gè)請(qǐng)求，并將在文檔中針對(duì)每個(gè)請(qǐng)求顯示。

 

 

如果您的一個(gè)端點(diǎn)要求的授權(quán)類(lèi)型不同于集合中的授權(quán)類(lèi)型，則可以在“請(qǐng)求”選項(xiàng)卡中將該授權(quán)類(lèi)型添加到請(qǐng)求中，并將在文檔中呈現(xiàn)該授權(quán)類(lèi)型。

 

 

在文檔中使用示例

您可以在集合中包括示例請(qǐng)求和響應(yīng)數(shù)據(jù)，它們將出現(xiàn)在文檔中。您的請(qǐng)求中包含的任何正文數(shù)據(jù)將顯示在文檔的端點(diǎn)部分。

 

 

您還可以創(chuàng)建用于請(qǐng)求的示例。 單擊示例>添加示例。

 

 

創(chuàng)建要添加的示例，然后單擊保存示例。

 

 

您在示例中包含的所有數(shù)據(jù)都將在docs示例代碼側(cè)欄中顯示在右側(cè)，作為響應(yīng)正文和標(biāo)頭。

 

 

Postman當(dāng)前支持這些編程語(yǔ)言或框架來(lái)自定義您的代碼片段。

 

文檔鏈接

您可以鏈接到生成的文檔中的標(biāo)題，包括簡(jiǎn)介、請(qǐng)求、文件夾和響應(yīng)。

這些鏈接是使用ID從您的文檔中生成的。 要找到鏈接，請(qǐng)單擊左側(cè)邊欄中的相關(guān)部分，然后您將在瀏覽器地址欄中看到它（或右鍵單擊并復(fù)制鏈接）。 然后，您可以使用此鏈接直接鏈接到文檔頁(yè)面部分。

 

 

您無(wú)法通過(guò)手動(dòng)創(chuàng)建ID鏈接到文檔的另一部分。

 

在文檔中使用圖像

您可以在文檔中包含在線托管的任何圖像。 使用Markdown圖片語(yǔ)法，如下所示：

 

Markdown演示集

您可以使用Postman Markdown集合來(lái)查看Markdown如何在文檔和Postman應(yīng)用程序中呈現(xiàn)。

 

 

您還可以通過(guò)瀏覽模板來(lái)查看使用Postman集合發(fā)布的文檔示例。 單擊“新建”，選擇“模板”選項(xiàng)卡，選擇一個(gè)模板，然后單擊“查看文檔”。

 

 

如果您在網(wǎng)上編輯文檔（遵循Postman應(yīng)用程序中收藏夾中的鏈接，或者在瀏覽器中登錄帳戶時(shí)遵循儀表板中的鏈接），則將看到常見(jiàn)格式設(shè)置選項(xiàng)的助手，并能夠預(yù)覽更改。