跳到主要内容

编写文档（Writing）

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

为了帮助你的队友（ 或全世界 ）更好地了解你正在构建的内容，请为你的收藏及其中的项目添加详细描述。使用 Postman 编辑器查看你编写的内容的外观。 或者使用经典的 Markdown 编辑器，使用 Markdown 语法 构建和格式化你的描述。你的所有描述都包含在你收藏的文档中。

你还可以在创建新请求 时添加说明。

向你的文档添加描述​

使用描述告诉使用你的收藏的人更多关于你的收藏的用途和每个请求的目的。使用标题构建描述并添加文本、表格、图像和链接等内容。

要添加或编辑现有集合、文件夹或请求的描述，请执行以下操作：

  1. 在边栏中选择集合，然后选择一个集合、文件夹或请求。

  2. 文档图标 选择右侧栏中的文档图标 。

    如果你的集合有 gRPC 请求 或 WebSocket 请求 ，则文档图标 文档图标 不可用于集合或文件夹。在边栏中选择一个收藏或文件夹以编辑其描述。

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

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

    切换编辑器

  5. 完成后，选择保存以保存文档。如果你需要进行更改，可以再次编辑说明。

要向用户提供有关你集合中的请求的更多详细信息，请向请求 参数和 header 添加说明。

在 Postman 编辑器中编写描述​

要使用富文本编辑工具编写描述，请选择Postman 编辑器选项。你可以使用 Postman 编辑器编写描述，而无需编写任何 Markdown 代码。使用工具栏上的工具来处理文本和其他内容，就像在典型的文字处理器中一样。或者使用常用的键盘快捷键来设置文本格式，例如⌘+B或Ctrl+B将文本设为粗体。

Postman 编辑器

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

Postman 编辑器工具栏

在没有 Markdown 的情况下创建表格。无需大惊小怪地使用 Markdown 代码来让你的表格正常工作。要添加表格，请选择表格工具。要添加或删除列或行，或删除表格，请选择一个单元格，然后选择快捷菜单。

Postman 编辑器表快捷方式

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

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

使用 Markdown 快捷方式

用 Markdown 写描述​

要使用 Markdown 编写描述，请选择经典 Markdown 编辑器选项。使用标准的 Markdown 语法 来创建你的内容：

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

在你工作时，选择“预览”选项卡以查看文档的显示方式并确保格式正确。要继续编辑，请选择Markdown选项卡。

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

降价编辑器

选择默认文档编辑器​

你可以选择要用于在 Postman 中编辑文档描述的默认编辑器。当你编辑描述时，Postman 将切换到你首选的编辑器。（你仍然可以在编辑描述时在 Postman 和 Markdown 编辑器之间切换。）

  1. 设置图标 选择标题中的设置图标 ，然后选择设置。
  2. 在 User Interface下，选择默认文档编辑器（Postman 编辑器或 Markdown 编辑器）。

为参数和标题添加描述​

为参数和 header 添加说明，以帮助其他人理解和使用你集合中的请求。打开请求并在键值对旁边的框中输入描述。

参数说明

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

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

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

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

文档中的授权类型

包括例子​

示例是成对的请求和响应，显示你的端点正在运行。 你添加到集合中的 任何示例都会自动包含在文档中。对于每个请求，你的文档都会显示示例代码片段以及示例响应正文和 header。

当你查看集合的 完整文档或 查看已发布的文档 时，会显示示例。

文档中的示例

添加链接​

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

  • 要使用 Postman 编辑器添加链接，请选择链接工具。粘贴或输入 URL 和链接文本，然后选择添加。（如果你以后需要更改链接，请选择它，然后选择编辑图标 编辑图标 。）

    添加链接

  • 要使用 Markdown 编辑器添加链接，请使用以下语法：

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

添加图像​

图像使你的文档生动起来，并帮助你更清晰地表达你的想法。你可以从计算机上传图像文件或嵌入在线托管的图像。

上传图像​

要使用 Postman 编辑器上传图像，请选择图像工具并选择浏览。选择你要上传的图像，然后选择打开。Postman 编辑器支持 GIF、JPG、PNG 和 SVG 格式。支持的最大图像大小为 5 MB。

你还可以通过将图像复制并粘贴到 Postman 编辑器或将图像文件拖到 Postman 编辑器来上传图像。

上传图像

嵌入图像​

你的图像必须在线托管（例如，在网站上），然后才能将其嵌入文档中。

  • 要使用 Postman 编辑器嵌入图像，请选择图像工具并选择嵌入 URL。粘贴或输入图像的 URL，然后选择嵌入。

    嵌入图像

  • 要使用 Markdown 编辑器嵌入图像，请使用以下语法：

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

编辑图像​

你可以在上传或嵌入图片后对其进行更改：

  • 要在 Postman 编辑器中更改图像，请先选择它，然后选择删除图标 删除图标 。然后上传或嵌入新图像。
  • 要在 Markdown 编辑器中更改图像，请根据需要编辑 Markdown 代码。
  • 要调整图像大小，请在 Postman 编辑器中选择图像并拖动调整大小手柄。width你还可以在 Markdown 编辑器中为 指定一个新值。
  • 要添加或编辑标题，请在 Postman 编辑器中选择图像并在图像下方输入标题。

图像存储限制​

如果你使用的是 Postman Free 计划 并且不是团队的一员，则上传图片的总大小限制为 20 MB。如果你是团队的一员（ 免费或付费计划 ），则你团队上传图片的总大小限制为 100 MB。

要检查你使用了多少存储空间，请转到你的 计费仪表板 并选择Resource Usage。上传的图像和文件使用的空间量显示在存储使用情况下。要升级你的可用存储空间，请联系 Postman support 。

当你达到存储限制的 90% 及以上时，每次尝试添加图像时都会收到警告。要详细了解 Postman plan 中包含的资源以及达到使用限制时会发生什么，请转到 关于资源使用 。

嵌入视频​

你可以在文档中嵌入 YouTube 或 Vimeo 上托管的视频。你的文档显示视频的预览，用户可以选择预览开始播放而无需离开 Postman。

你不能嵌入在 YouTube 和 Vimeo 以外的服务上托管的视频，但你可以添加指向该视频的 链接。

  • 要使用 Postman 编辑器嵌入视频，请选择视频工具。粘贴或输入视频的 URL，然后选择嵌入。

    嵌入视频

  • 要使用 Markdown 编辑器嵌入视频，请使用以下语法：

    <video src="https://youtube.com/embed/1xTTNGacuaQ" alt="Set Up Live Collections" width="340" height="170"></video>

编辑文档时无法播放视频。选择保存，然后选择要开始播放的视频。

你可以在上传或嵌入视频后对其进行更改：

  • 要在 Postman 编辑器中更改视频，请先选择它，然后选择删除图标 删除图标 。然后嵌入一个新视频。
  • 要在 Markdown 编辑器中更改视频，请根据需要编辑 Markdown 代码。
  • 要调整视频预览的大小，请在 Postman 编辑器中选择视频并拖动调整大小手柄。width你还可以在 Markdown 编辑器中为 指定一个新值。
  • 要添加或编辑标题，请在 Postman 编辑器中选择视频并在视频下方输入标题。

寻找帮助和灵感​

在使用 Markdown 时需要一些帮助吗？查看 Postman Markdown 演示集合， 了解 Markdown 在已发布文档中的格式。选择“在 Postman 中运行”按钮以将演示集合添加到你的工作空间并查看 Markdown 代码。

Markdown 演示合集

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

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

  2. 在左侧窗格中选择Teams、Workspaces、API或Collections 。

    公共 API 网络页面

  3. 选择一个团队、工作空间、API 或集合以访问由属于公共 API 网络的其他人编写的文档。

    文档示例