跳到主要内容

生成文档（Generating）

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

为集合或 API 生成文档后，用户可以在 Postman 中 查看文档。 默认情况下，你的文档是私有的，因此你必须先与他人共享集合或 API，然后他们才能访问它。如果你正在创建一个公共 API，你可以 发布你的文档 以使其对任何使用网络浏览器的人公开可用。

记录集合​

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

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

要添加说明，请执行以下操作：

  1. 在边栏中选择集合，然后选择一个集合、文件夹或请求。
  2. 文档图标 选择右侧栏中的文档图标 。
  3. 编辑图标 选择描述旁边的编辑图标 。
  4. 撰写你的新内容，然后选择保存。要了解有关使用 Postman 的内置编辑工具的更多信息，请参阅 编写文档 。

文档窗格

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

记录 gRPC 和 WebSocket 集合​

具有 gRPC 或 WebSocket 请求的集合使用与具有 HTTP 请求的集合不同的格式。你可以查看文档并添加 gRPC 或 WebSocket 请求的描述。你还可以在集合的概述选项卡上添加描述，但你无法查看或编辑完整集合的文档。了解有关 记录 gRPC 请求 或 记录 WebSocket 请求的 更多信息。

生成 API 文档​

API Builder 提供了一个位置来查看、创建和管理你的所有 API 文档。Postman 自动为任何 OpenAPI 2.0 或 3.0 定义生成 API 文档。你还可以通过从 API 生成集合或添加现有集合的副本来向任何 API 添加详细文档。

查看架构文档​

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

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

要查看 OpenAPI 2.0 或 3.0 API 的文档，请执行以下操作：

  1. 在边栏中选择API ，然后选择一个 API。
  2. 在 API 的概述中，在Definition下，选择View schema documentation。

查看架构文档

为 API 创建新文档​

要为 API 文档生成新集合，请执行以下操作：

  1. 在边栏中选择API ，然后选择一个 API。
  2. 在 API 的概述中，在Collections旁边，选择+并选择Generate from API definition。
  3. 更改任何设置以自定义新集合。
  4. 选择生成集合。

新集合显示在你的 API 概览和侧边栏中的 API 下方。要查看集合的文档，请展开集合并选择查看完整文档。

生成新的 API 文档

将现有文档添加到 API​

要将现有集合用于 API 文档，请执行以下操作：

  1. 在边栏中选择API ，然后选择一个 API。
  2. 在 API 的概述中，在Collections旁边，选择+并选择Copy existing collection。
  3. 选择一个可用的集合并选择复制集合。

集合的副本显示在你的 API 概览和侧边栏中的 API 下方。要查看集合的文档，请展开集合并选择查看完整文档。

添加现有的 API 文档

添加集合时，会将集合的独立副本添加到 API。API 中的副本将不再与原始副本同步。如果你移动或删除 API，则该 API 中包含的任何集合都会随之移动或删除。

编辑 API 文档​

你可以从 API Builder 添加到你的 API 文档集合。

要编辑 API 的文档集合，请执行以下操作：

  1. 在边栏中选择API ，然后选择一个 API。
  2. 在 API 的概述中，展开一个集合并选择View full documentation。
  3. 编辑图标 选择任何描述旁边的编辑图标 ，然后使用 内置的编辑工具 编写内容。

无法直接编辑架构文档。相反， 编辑你的 API 定义 ，然后选择Save。Postman 会自动更新 API 文档以反映对你的定义的最新更改。

编辑 API 文档

删除 API 文档​

要从 API 中删除文档集合，请执行以下操作：

  1. 在边栏中选择API ，然后选择一个 API。
  2. 在 API 的概览中，将鼠标悬停在集合上并选择删除图标 删除图标 。
  3. 选择删除。

将环境与文档相关联​

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

如果关联的环境也与他们共享，则使用你的集合的任何人都将能够查看文档中的变量。对于公共文档，你可以在 发布过程 中选择一个环境。发布环境后，任何 查看公共文档 的人都可以使用它。

要在文档中使用环境变量，请执行以下操作：

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

引用一个变量

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

下一步​

在 Postman 中生成 API 文档后，你可以编辑和格式化文档并发布它们。

  • 要了解有关编辑和格式化文档的更多信息，请访问 编写文档 。
  • 要了解如何公开你的文档，请访问 发布你的文档 。