记录您的 API

文档是任何集合或 API 的重要组成部分。好的文档可以帮助使用您的集合的人了解它的作用以及每个请求的工作方式。全面的 API 文档让您的消费者知道哪些端点可用以及如何与它们成功交互。

为您的集合或 API 生成文档后，用户可以在 Postman中查看文档。默认情况下，您的文档是私有的，因此只有与您共享集合或 API 的人才能看到它。如果您正在创建一个公共 API，您可以发布您的文档，让任何拥有 Web 浏览器的人都可以使用它。

内容

记录集合

Postman 会自动为您创建的任何集合生成基本文档。查看文档以查看集合中所有请求的详细信息，以及各种客户端语言的示例代码。请求详细信息包括方法、授权类型、URL、标头、请求和响应结构以及示例。此外，该文档还显示了请求参数、标头和正文的所有键值对。

要使您的文档对用户更有价值，请为您的收藏中的项目添加描述。您添加的任何描述都会自动包含在您收藏的文档中。

  1. 在边栏中选择收藏，然后选择收藏、文件夹或请求。
  2. 在上下文栏中选择文档。 文档图标
  3. 编辑图标选择描述旁边的编辑图标。
  4. 撰写新内容，然后选择保存。要了解有关使用 Postman 内置编辑工具的更多信息，请参阅创作您的文档。
文档窗格

查看集合的完整文档时，您还可以编辑描述。选择文档窗格底部的查看完整集合文档，然后像往常一样编辑描述。

生成 API 文档

API Builder 中的文档选项卡提供了一个查看、创建和管理所有 API 文档的位置。Postman 自动为 API Builder 中定义的任何 OpenAPI 3.0 模式生成 API 文档。您还可以通过从 API 生成集合或链接到现有集合来将详细文档添加到任何 API。

一个集合只能链接到一个 API 版本。如果您创建API 的新版本，您还需要生成一个新集合来保存该版本的文档。要了解更多信息，请参阅版本化您的文档。

查看架构文档

如果您正在设计基于 OpenAPI 3.0 规范的 API，Postman 会根据您的模式定义自动创建文档。

API 文档包括完整的 API、路径和操作信息，例如认证方法、参数、请求体、响应体和标头以及示例。该文档还包括各种数据模型的架构信息，例如所需的属性、默认值、最小值和最大值以及其他约束。

要查看 OpenAPI 3.0 架构的文档：

  1. 在左侧边栏中选择API，然后选择 API 和版本。
  2. 选择文档选项卡。
  3. 在左侧窗格中，选择Schema Documentation下的项目以查看特定路径或请求。
查看架构文档

如果您的 API 架构包含未保存的更改或错误，邮递员会提醒您。要使用最新的架构更改更新 API 文档，请选择定义选项卡并保存您的架构。

为 API 创建新文档

要为 API 文档生成新集合：

  1. 在左侧边栏中选择API，然后选择 API 和版本。
  2. 选择概览选项卡。
  3. 选择文档旁边的+，然后选择创建新文档。
  4. 输入新集合的名称。（让它与你的这个版本的 API 相关联。）
  5. （可选）选择显示高级设置并根据需要更改任何设置。请参阅每个设置的说明以了解更多信息。
  6. 选择创建文档。新的 API 文档显示在“文档”选项卡中。
生成新的 API 文档

您可以从“文档”选项卡生成其他文档集合。在左侧窗格中，选择Collection Documentation旁边的+，然后选择Create Documentation。

将现有文档添加到 API

要将现有集合用于 API 文档：

  1. 在左侧边栏中选择API，然后选择 API 和版本。
  2. 选择概览选项卡。
  3. 选择文档旁边的+，然后选择添加现有文档。
  4. 选择要用于 API 文档的集合。
  5. 选择添加文档。API 文档显示在“文档”选项卡中。
添加现有 API 文档

您可以从“文档”选项卡添加其他文档集合。在左侧窗格中，选择Collection Documentation旁边的+，然后选择Add Existing Documentation。

编辑 API 文档

您可以直接从“文档”选项卡添加到 API 文档集合。首先，在左窗格中选择一个链接的集合。编辑图标然后选择任何描述旁边的编辑图标，并使用内置的编辑工具来创作内容。

处理 API 文档的另一种方法是打开链接的集合。在文档选项卡中，选择右上角的查看集合，然后编辑链接集合中的文档。

无法在“文档”选项卡中编辑架构文档。相反，在定义选项卡中编辑您的架构，然后选择保存。Postman 会自动更新 API 文档以反映最新的架构更改。

编辑 API 文档

删除 API 文档

要从 API 中删除链接的文档集合：

  1. 在左侧边栏中选择API，然后选择 API 和版本。
  2. 选择概览选项卡。
  3. 删除按钮选择要从此 API 版本中删除的集合旁边的删除按钮。
  4. 选择删除文档。

删除文档只会删除集合和 API 版本之间的链接。集合本身不会被删除。

将环境与文档相关联

环境是可以在 Postman 请求中使用的一组相关变量。在集合中创作描述时，您还可以引用变量。在每种情况下，变量的初始值都会自动填充到文档中。

如果关联的环境也与他们共享，任何使用您的集合的人将只能查看文档中的变量。对于公共文档，您可以在发布过程中选择环境。发布环境使其可供查看公共文档的任何人使用。

要在文档中使用环境变量：

  1. 如果一个新环境尚不存在，请创建一个新环境。
  2. 通过在环境下拉列表中选择环境来激活环境。
  3. 如果需要，向环境中添加一个新变量。
  4. 向集合中的请求或描述添加对变量的引用。
引用变量

如果有人从您的文档中使用Run in Postman按钮导入集合，他们还将导入环境和任何相关变量。变量的初始值在您的文档中发布，因此请确保它们不包含任何敏感数据。

版本化您的文档

版本是您的 API 提供给消费者的一组特性和功能。包含 API 文档的集合只能链接到 API 的一个版本。这意味着，当您创建 API 的新版本时，您还需要创建新的文档集合。然后，您可以使用新集合为新 API 版本创作文档。

有几种方法可以为 API 的新版本创建文档集合：

  • 创建 API 版本时保留文档。创建新的 API 版本时，您可以选择将元素从以前的 API 版本复制到新版本中。选择Documentation元素，然后选择Create Version。这将基于先前的集合创建一个新的文档集合，并将新版本名称附加到集合名称。

    创建新版本

  • 从新的 API 版本生成一个集合。打开新的 API 版本并选择概览选项卡。选择文档旁边的+，然后选择创建新文档。

  • 将现有的集合添加到新的 API 版本。打开新的 API 版本并选择概览选项卡。选择文档旁边的+，然后选择添加现有文档。

Postman 会根据每个版本的 API 定义自动为每个版本的 API 生成架构文档。对 API 进行版本控制后，您将在“文档”选项卡中看到新版本的架构文档。

记录发布

发布是 API 版本中较小的增量更改单元。您可以将文档更改作为 API 版本的一部分。与您共享收藏的任何人都可以使用发布标签下拉列表查看特定版本的完整文档。对于公共文档，您可以选择在发布过程中包含哪些版本。

要记录 API 版本的新版本：

  1. 在创建版本之前，根据需要编辑 API 文档。
  2. 创建API 版本的新版本。
  3. 如果文档是公开的，请编辑发布设置以包含新版本。

查看版本

下一步

了解有关使用 Postman 的内置编辑工具创作文档、发布文档以使其公开可用以及查看文档的各种方式的更多信息。