如何使用 Postman 生成 API 文档

引言

应用程序编程接口（API）文档是软件开发的重要组成部分，它使开发人员能够高效地理解和使用 API。它就像一本详细的手册，概述了各种 API 端点、方法、请求参数和响应类型。良好的文档能够使集成更加顺畅，并整体提升使用您 API 的开发人员体验。API 文档提供了使用 API 的系统化分解。

• 端点： 提供 API 访问的 URL 称为端点。
• 方法： 每个端点都可以使用以下 HTTP 方法之一来访问：GET、POST、PUT、DELETE。
• 参数： 包括请求所需的正文数据、路径变量、查询参数和标头。
• 请求示例： 展示 API 功能的示例查询。
• 响应详细信息： 响应的详细信息，包括错误消息和状态码，以及它们的内容和结构。
• 身份验证： 验证请求的指南，通常使用令牌或 API 密钥。

API 文档的重要性

• 易用性： 完善的文档有助于开发人员快速掌握 API 的功能，从而缩短实现时间和学习曲线。
• 减少错误： 定义明确的协议有助于避免错误和误解，确保 API 请求的准确制定和处理。
• 支持与维护： 对文档齐全的 API 进行维护和支持更为简单。开发人员可以使用文档进行故障排除，而无需 API 提供商提供全天候支持。
• 采用与集成： 优质的文档可以使开发人员更容易地将 API 集成到他们的应用程序中，从而促进其采用。
• 专业性与信任： 编写良好的文档传达了组织对质量和用户支持的承诺。

Postman 作为 API 文档工具

开发人员通常使用 Postman 这个流行的工具来测试、创建和描述 API。该工具提供了一个直观的界面和一套全面的功能，有助于创建和管理 API 文档。

• 集合： Postman 允许用户将相似的 API 查询聚合到集合中，从而简化了复杂 API 的组织和管理。
• 环境变量： 此功能允许用户为不同的上下文（如开发、测试和生产）设置变量，从而简化了在环境之间切换的过程。
• 请求和响应检查： Postman 通过提供对请求和响应数据的全面洞察，帮助开发人员进行故障排除和改进他们的 API。
• 自动文档生成： Postman 可以从集合中自动生成文档，确保其始终与最新的 API 修改保持同步。
• 协作： 通过使用共享工作区进行 API 开发和文档记录，团队可以协作以确保项目整体的正确性和一致性。

Postman

Postman 是一个用于开发 API 的有效工具，它使创建、评估和记录 API 的过程更加容易。凭借其直观的用户界面，开发人员可以轻松创建和管理 API 请求和集合。凭借环境变量管理、自动化测试和通信工具等功能，Postman 已成为大小开发团队不可或缺的工具。

下载和安装 Postman

• 访问 Postman 网站： 要访问 Postman 官方网站，请访问 [postman.com](https://www.postman.com/)。
• 获取 Postman： 在主页菜单中选择“Download”（下载）。Postman 与 Windows、macOS 和 Linux 等操作系统兼容。选择适合您操作系统的版本。
• 安装 Postman： 下载完成后，打开安装文件并按照安装说明进行操作。这是一个简单的过程，通常包括选择安装位置和接受服务条款。
• 启动 Postman： 安装完成后，打开 Postman。将出现一个欢迎页面，并引导您完成一些基本的设置说明。

创建 Postman 账户

• 启动 Postman： 如果您最近安装了 Postman，它应该会自动启动。如果未自动启动，请从“开始”菜单或程序文件夹中打开 Postman。
• 创建新账户： 如果您还没有账户，请在欢迎页面上选择“Sign Up for Free”（免费注册）。您可以使用 GitHub 账户、Google 账户或电子邮件地址进行注册。
• 填写您的信息： 如果您选择使用电子邮件地址注册，请确保输入您的电子邮件地址、设置密码并提供任何其他必需的信息。“Create Free Account”（创建免费账户）将打开。
• 验证您的电子邮件： 查找来自 Postman 的验证电子邮件。要激活您的账户，请单击验证链接。
• 登录 Postman： 账户验证后，使用您的登录信息访问 Postman。然后，您可以同步数据、查看您的工作区并探索 Postman 的功能。

Postman 界面

Postman 界面设计得用户友好且直观。

• 标题工具栏： 您可以使用标题工具栏中的工具来创建新环境、集合和请求。还可以轻松访问通知、工作区切换器和帐户设置。
• 侧边栏： 左侧的侧边栏显示您的集合、环境、API 和其他资源。此面板可以根据需要展开或收起。
• 请求构建器： 这是 UI 的主要区域，您可以在此处构建和自定义 API 请求。您可以在此处输入 URL，添加标头、参数和正文数据，并选择请求方法（GET、POST、PUT、DELETE 等）。响应查看器：请求构建器下方是响应查看器，其中显示 API 请求的结果。这包括响应正文、标头、状态码和请求花费的时间。
• 集合选项卡： 您可以使用集合来聚合您的 API 查询。每个集合可能包含多个请求、文件夹和示例。您必须使用此选项卡来管理和记录您的 API。
• 环境管理器： Postman 允许您定义环境，即变量集合，用于您的请求构建。通过环境管理器，可以轻松地在不同环境之间切换，从而更容易在不同情况下测试您的 API。
• 控制台： Postman 控制台允许您查看您进行的每次 API 调用的详细日志。它是用于调试和故障排除的有效工具。

在 Postman 中设置您的 API

创建新集合

在 Postman 中，集合是一组有意义的、有组织的请求。您可以像文件夹一样在其中存储和排列您的 API 查询。此功能非常适用于组织和与同事共享大量 API 调用。各种请求类型、文档、预请求脚本和测试是集合的一些示例。

• 打开 Postman： 在您的计算机上打开 Postman 程序。
• 找到集合： “集合”选项卡位于左侧侧边栏。单击该按钮。
• 通过选择“集合”选项卡旁边的“New”（新建）或“+”按钮来启动一个新集合。然后单击下拉菜单并选择“Collection”（集合）。
• 您将看到一个对话框，要求您为集合命名。给您的集合起一个有意义的名称，以表达其目的。
• 编写描述（可选）： 您可以编写描述来提供有关集合的更多信息。
• 保存集合： 单击“Create”（创建）或“Save”（保存）以完成您的集合的构建。

您现在可以从“集合”菜单中选择您新创建的集合来添加请求。

将请求添加到集合

1. GET、POST、PUT、DELETE 请求

API 调用有多种类型，有时也称为 HTTP 方法。每种方法都有其独特的功能。

• GET： 用于从服务器检索数据。
• POST： 通过向服务器发送数据来创建新资源。
• PUT： 修改服务器上已存在的资源。
• DELETE： 从服务器删除一个条目。

要将请求添加到您的集合：

• 选择集合： 单击要添加请求的集合。
• 添加请求： 使用请求选项卡中的“+”按钮或集合视图中的“Add Request”（添加请求）按钮。
• 为请求命名： 给请求起一个能清晰表明其意图的名称。
• 选择 HTTP 协议： 从请求 URL 框旁边的下拉菜单中选择 GET、POST、PUT 或 DELETE。
• 在此处键入请求 URL： 输入要向其发送请求的 URL 端点。
• 保存请求： 单击“Save”（保存）按钮将请求添加到您的集合。

2. 设置请求参数

请求通常需要参数来过滤数据或定义条件。根据类型，这些特性可以输入在不同的部分。

• 查询参数： 在 GET 请求中用于过滤数据。
  
  • 导航到“Params”（参数）部分。
  • 在此处输入参数的键和值。
• 路径变量： 用于指定 URL 的动态部分。
  
  • 在 URL 中，使用花括号 {{}} 来表示路径变量。
  • 在“Path Variables”（路径变量）部分定义这些变量。
• 正文参数： 在 POST 和 PUT 请求中用于向服务器传输数据。
  
  • 访问“Body”（正文）选项卡。
  • 选择格式（JSON、form-data 等）。
  • 在此处输入您希望发送的键值对。

在集合内组织请求

保持集合内请求的组织性有助于建立一个整洁有效的 API 工作空间。

• 创建文件夹： 将相关请求分组到文件夹中。
  
  • 单击集合。
  • 选择“Add Folder”（添加文件夹）并为其命名。
  • 将请求移动到文件夹内。
• 重新排列请求： 通过单击并拖动来重新排列集合内的请求或文件夹。
• 标记请求： 使用标签按功能、优先级或其他任何规格对请求进行分组。在请求的描述中包含标签，或将其作为自定义字段。

记录您的 API

为集合和请求添加描述

您应该为请求和集合添加描述，以提高理解和清晰度。通过阅读描述，用户可以更好地理解每个请求的作用以及它如何融入更大的 API 结构。

1. 为集合添加描述

• 打开 Postman，选择您想要记录的集合。
• 要编辑集合名称，请单击三个点（省略号）并选择“Edit”（编辑）。
• “Edit Collection”（编辑集合）模态框中有一个“Description”（描述）字段。在此部分，您可以提供集合的详细解释，包括其目标和包含的请求类型。
• 使用简单明了的语言，以便于理解。

2. 为请求添加描述

• 选择要在集合中进行文档化的请求。
• 在请求构建器中，单击请求名称下方的选项卡中的“Documentation”（文档）。
• 在“Description”（描述）字段中，提供对请求功能的详细描述，确保包含任何相关的标头、参数或正文信息。
• 突出任何用户需要注意的特定行为或边缘情况。

使用 Markdown 增强文档

Markdown 是一种轻量级标记语言，可帮助格式化纯文本文档。通过 Postman 对 Markdown 的支持，您可以生成易于阅读且结构良好的文档。

1. Markdown 基础知识

• 标题： 使用 `#` 表示 H1，`##` 表示 H2，`###` 表示 H3，依此类推。

• 粗体和斜体： 使用 `**粗体**` 或 `__粗体__` 表示粗体文本，使用 `*斜体*` 或 `_斜体_` 表示斜体文本。

• 列表： 使用 `-` 或 `*` 表示无序列表，使用数字表示有序列表。

• 代码块： 使用反引号表示内联代码，使用三个反引号表示代码块。

2. Postman 中的 Markdown 示例

• 添加带标题和列表的描述。

• 包含代码片段

添加代码片段和示例

提供客户示例和代码片段可以帮助他们更轻松地理解如何有效地使用您的 API。

1. 自动生成代码片段

• Postman 可以自动生成多种编程语言的代码片段。
• 在构建好请求后，从请求构建器的右侧菜单中选择“Code”（代码）按钮。
• 多种语言（例如 cURL、JavaScript、Python）的代码示例将显示在一个模态窗口中。
• 选择首选语言并复制，以将示例包含在您的文档中。

2. 自定义示例

• 在请求构建器中选择“Examples”（示例）选项卡。
• 要添加新示例，请单击“Add Example”（添加示例）。
• 为示例命名，输入请求和响应信息，然后选择“Save”（保存）。
• 您可以提供多个示例来演示不同的用例或场景。

在文档中使用环境变量

1. 创建和管理环境

• 在 Postman 中，单击右上角的齿轮图标，然后选择“Manage Environments”（管理环境）。
• 要启动一个新环境，请单击“Add”（添加）。
• 指定您需要的变量（如 {baseUrl{ 和 {apiKey{）及其初始值。
• 在请求构建器中保存环境，并从环境下拉菜单中选择它。

2. 在请求和文档中引用变量

• 在文档和请求中引用环境变量时，使用双花括号。例如，baseUrl/endpoint。
• 此方法可确保您的请求和文档始终具有灵活性，并随时准备适应新情况。

示例

生成 API 文档

Postman 是一个出色的工具，除了作为强大的 API 测试工具外，还可以创建全面的 API 文档。借助 Postman 的文档工具，开发人员可以自动生成 API 文档，从而使其他人更容易使用 API。这是 Postman 原生集成的一项功能，可以更轻松地创建、编辑和发布 API 文档。

生成文档的步骤

1. 选择要记录的集合

在开始生成文档之前，您必须先选择包含您想要记录的 API 查询的集合。

• 打开 Postman： 在您的计算机上打开 Postman 程序。
• 转到集合页面： 单击左侧侧边栏中的“Collections”（集合）选项卡，以查看所有集合的列表。
• 选择一个集合： 要记录一个集合，请单击它。这将使集合深入显示，展示其中所有的请求和文件夹。
• 生成文档： 单击集合名称旁边的省略号（三个点）以查看或发布文档。

2. 配置文档设置

选择集合后，您可以配置文档的设置。

• 标题和摘要： 为您的文档提供标题和摘要。这为用户提供了 API 功能的概述。
• 可见性设置： 选择是否允许公开访问文档。私有文档仅对指定的人员或团队可用，而公共材料则对拥有 URL 的任何人都可以访问。
• 版本控制： 如果您的 API 有多个版本，您可以指定文档适用于哪个版本。

自定义生成的文档

1. 主题和布局选项

Postman 提供了多种选择来个性化您的文档外观。

• 主题： 从一系列预制主题中选择，以改变文档的外观和感觉。这些主题允许您更改字体、颜色和整体外观。
• 布局选项： 根据您的 API 的复杂性和用户的需求来定制数据的排列方式。

2. 添加自定义 CSS 和 JavaScript

您可以包含自定义 CSS 和 JavaScript 来实现更高级的定制。

• 自定义 CSS： 添加您自己的 CSS 来替换默认样式，以确保文档符合您品牌的视觉标识。
• 自定义 JavaScript： 您可以使用 JavaScript 为文档提供交互式功能或独特的功能。

发布文档

1. Postman 公共文档

发布您的材料可以让您期望的受众获取它。

• 单击公共文档的“Publish”（发布）按钮。然后，您就可以向用户提供您将收到的可共享链接。
• 访问控制： 任何拥有公共文档 URL 的人都可以查看它们。因此，确保机密信息不会出现在公共文档中非常重要。

2. 共享文档链接

发布后，您可以将文档分发给团队成员或其他用户。

• 复制链接： 使用提供的链接通过电子邮件、聊天或任何其他通信方式发送文档。
• 嵌入到其他平台： 通过在您的网站、项目管理软件或其他平台中嵌入文档链接，为用户提供便捷的访问。

3. 将文档嵌入您的网站

您可以将 Postman 文档直接集成到您的网站中，以实现无缝集成。

• 嵌入代码： 您可以复制 Postman 提供的嵌入代码。
• 插入到 HTML： 将嵌入代码粘贴到您希望文档显示在网站 HTML 中的位置。
• 自定义嵌入设置： 调整宽度、高度和其他参数，以确保嵌入的文档能很好地与您网站的设计融为一体。

结论

使用 Postman 生成 API 文档是一种简化的方法，可以提高 API 的可读性和可用性。通过利用 Postman 强大的文档工具，您可以快速创建、编辑和发布全面的文档。该过程包括选择正确的集合、配置文档首选项以及使用 JavaScript、CSS 和主题进行外观调整。在发布并可公开共享或直接集成到您的网站后，您的文档将易于导航且用户友好。这不仅有助于开发人员理解和使用您的 API，还促进了更好的协作和效率。Postman 的文档功能是任何致力于提供清晰、专业且易于理解的 API 文档的开发团队的宝贵资产。