创作您的文档

Postman会自动为您创建的每个集合生成文档。该文档包括您集合中的所有请求,以及示例、授权详细信息和示例代码。

为了帮助您的队友(或世界)更好地了解您正在构建的内容,请为您的收藏和其中的物品添加详细描述。使用 Postman 编辑器准确查看您的内容在您创作时的外观。或者使用经典的 Markdown 编辑器使用Markdown 语法构建和格式化您的描述。您的所有描述都包含在您收藏的文档中。

您还可以在创建新请求时添加描述。

内容

向您的文档添加描述

使用描述让使用您的收藏的人更多地了解您的收藏的用途以及每个请求的目的。使用标题构建您的描述并添加文本、表格、图像和链接等内容。

要添加或编辑现有集合、文件夹或请求的描述:

  1. 在边栏中选择收藏,然后选择收藏、文件夹或请求。

  2. 在上下文栏中选择文档。 文档图标

  3. 编辑图标选择描述旁边的编辑图标。

  4. 使用可视化Postman 编辑器或经典Markdown 编辑器编写您的描述。两者都是兼容的,因此您可以在工作时随意在两个编辑器之间切换。

    切换编辑器
  5. 完成后,选择保存以保存您的文档。如果您需要进行更改,只需再次编辑说明即可。

要向用户提供有关您集合中请求的更多详细信息,请在请求参数和标头中添加描述。

在 Postman 编辑器中创作描述

要使用富文本编辑工具创作描述,请选择Postman 编辑器选项。Postman 编辑器可以轻松编写描述,而无需编写任何 Markdown 代码。使用工具栏上的工具来处理文本和其他内容,就像在典型的文字处理器中一样。或者使用常用的键盘快捷键来格式化文本,例如⌘+BCtrl+B使文本变为粗体。无需预览您的内容即可看到最终外观——所见即所得!

邮差编辑

查看工具提示以在您工作时获得帮助。将光标悬停在工具栏上的某个项目上可查看该工具的说明和相关的键盘快捷键。如果工具栏上未显示所有工具,请选择三个点三个点图标

邮递员编辑器工具栏

使用表格既快速又简单。无需大惊小怪地使用 Markdown 代码即可让您的表格正常工作。要添加表格,请选择表格工具。要添加或删除列或行,或删除表格,请选择一个单元格,然后选择快捷菜单。

Postman 编辑器表格快捷方式

Postman 编辑器了解 Markdown 语法。如果您习惯使用 Markdown,请键入任何标准Markdown 代码以快速格式化文本。例如,键入#后跟空格以开始新标题,或键入---以添加水平线。要重用已经用 Markdown 编写的文档,只需复制现有的 Markdown 代码并将其粘贴到编辑器中即可立即对其进行格式化。

如果您从 Postman 编辑器复制内容,当您将内容粘贴到另一个应用程序(如文字处理器或电子邮件)时,该内容将保留其格式。

使用 Markdown 快捷键

在 Markdown 中编写描述

要使用 Markdown 编写描述,请选择Classic Markdown 编辑器选项。使用标准Markdown 语法来创建您的内容:

  • 使用标题、列表和表格构建内容
  • 使用粗体、强调和大引号格式化文本
  • 添加图像、链接和代码块

在您工作时,选择“预览”选项卡以查看您的文档将如何显示并确保其格式正确。要继续编辑,请选择Markdown选项卡。

在块元素(例如标题、段落和列表)之前和之后留一个空行以避免任何格式问题。

降价编辑器

向参数和标题添加描述

向参数和标头添加描述,以帮助其他人理解和使用您集合中的请求。打开请求并在键值对旁边的框中键入描述。

参数说明

有权访问您的集合的人或查看您发布的文档的任何人都可以看到参数和标题说明。描述与请求一起出现在文档中,位于参数或标头名称旁边。

即使未选中它们的复选框,所有键值对都包含在您的文档中。使用描述来说明哪些参数和标题是必需的,哪些是可选的。任何使用您的集合的人都可以选择在发送请求或生成代码片段时包含哪些键值对。

包括授权细节

您的文档会自动包含访问端点所需的授权类型。授权详细信息显示在集合描述下方以及文档中的每个请求下方。

如果您为集合指定授权详细信息,那么集合中的每个请求都会继承这些授权要求。如果您的端点之一需要不同的授权类型,请打开请求并更改授权详细信息。更改会反映在您的文档中。

文档中的授权类型

包括示例

示例是成对的请求和响应,它们展示了您的端点在行动。您添加到集合中的任何示例都会自动包含在文档中。对于每个请求,您的文档都会显示示例代码片段以及示例响应正文和标头。

仅当您查看集合的完整文档或查看已发布文档时,才会显示示例。

文档中的示例

使用链接将用户引导至您的存储库、网站或其他在线资源。

  • 要使用 Postman 编辑器添加链接,请选择链接工具。粘贴或键入 URL 和链接文本,然后选择添加。(如果您稍后需要更改链接,请选择它,然后选择编辑图标编辑图标。)

    添加链接
  • 要使用 Markdown 添加链接,请使用以下语法:

    [link text to display](https://your-link-url.com)

添加图像

图像使您的文档更加生动,并帮助您更清楚地表达您的想法。您的图像必须先在线托管,然后才能将其添加到您的文档中。

  • 要使用 Postman 编辑器添加图像,请选择图像工具。粘贴或键入图像 URL,然后选择添加。(如果您稍后需要更改图像,请选择它,然后选择编辑图标编辑图标。)

    添加图像
  • 要使用 Markdown 添加图像,请使用以下语法:

    ![image alt text](https://your-image-location.com)

寻找帮助和灵感

在使用 Markdown 时需要一些帮助吗?查看 Postman Markdown 演示集,了解 Markdown 在已发布文档中的格式。选择在 Postman 中运行按钮将演示集合添加到您的工作区并查看 Markdown 代码。

Markdown 演示合集

寻找一些文档灵感?浏览公共 API 网络以查找在 Postman 中创建的优秀文档的示例。

  1. 导航到公共 API 网络页面或在 Postman 标题中选择探索。

  2. 在左侧窗格中选择TeamsWorkspacesAPIsCollections 。

    公共 API 网络页面

  3. 选择一个团队、工作区、API 或集合以查看由公共 API 网络中的其他人创作的文档。

    文档示例

下一步

要公开您的文档,请参阅发布您的文档