跳到主要内容

指定示例（Specifying examples）

示例显示了你的 API 端点的运行情况，并提供了有关请求和响应如何工作的更多详细信息。你可以通过保存响应向请求添加示例，也可以创建带有自定义响应的示例来说明特定用例。创建示例后，你可以使用它们来设置模拟服务器或向 API 文档添加更多详细信息。

理解示例​

在 Postman 中，一个例子是由请求和相关响应组成的配对。每个示例都包含请求部分（方法、URL、参数、header 和正文）和响应部分（状态代码、正文和 header）。你可以通过将示例添加到集合中的请求来创建示例，一个请求可以有多个示例。

为一个请求提供多个示例有助于说明端点响应请求的不同方式。你可能有使用不同状态代码（例如 200 或 404）响应或返回不同数据（或根本没有数据）的示例。

示例有多种用途。开发人员和测试人员可以参考示例来更好地了解端点在不同场景中的功能。示例也可用于 设置模拟服务器 ，这样开发人员和测试人员就可以开始针对你的 API 编写代码 ——甚至在它完成之前。此外，你可以在 API 的 公共文档 中包含示例，以帮助世界上使用你的 API 的任何人。

添加示例​

一个示例总是与 集合 中的一个 请求 相关联，并且一个请求可以有多个示例。要向请求添加示例，请发送请求，然后将响应保存为示例。你还可以手动向请求添加示例并定义自定义响应。使用任一方法添加示例后，你可以随时对其进行编辑以进行更改。

为获得最佳 Postman 性能，示例响应必须小于 5 MB。

添加示例

保存响应作为示例​

在 Postman 中保存 回复 时，你可以选择将其保存为示例。

  1. 在边栏中选择收藏集。
  2. 打开请求并选择发送。
  3. 在响应窗格中，选择保存响应，然后选择另存为示例。

将响应保存为示例

你不能向 WebSocket 请求添加示例。对于 WebSocket 请求，你可以 将消息 与请求一起保存。

对于带有流方法的 gRPC 示例 ，你必须在将响应/消息流保存为示例之前结束流。

添加自定义示例​

通过自定义示例，你可以定义请求 和 响应 的 外观，包括状态代码和响应正文。

  1. 在边栏中选择收藏集。
  2. 更多操作图标 选择请求旁边的更多操作图标 ，然后选择添加示例。
  3. 输入示例的名称。
  4. 编辑示例的请求部分。
    • 根据需要添加任何参数或 header。
    • 输入请求正文并选择内容类型。
  5. 编辑示例的响应部分。
    • 输入状态代码（例如 200 或 404）。
    • 输入响应正文并选择内容类型。
    • 根据需要添加任何 header。
  6. 选择保存以保存示例。

添加自定义示例

尝试一个例子​

示例与其关联的请求一起存储在一个集合中。你可以通过在新选项卡中将示例作为请求打开来尝试示例。

  1. 在边栏中选择收藏集。

  2. 选择一个请求，然后选择一个示例将其打开。

  3. 选择尝试在新选项卡中将示例作为请求打开。该请求将自动发送到新选项卡中。

    尝试示例

  4. 查看请求和响应详细信息。

    打开示例作为请求

    新请求不会自动保存。

    你正在尝试的示例的名称位于工作台中请求名称的旁边。选择示例的名称以在单独的选项卡中将其打开。

    选择示例名称

  5. 或者，你可以选择保存以将新请求保存到工作空间中的新集合或现有集合。

  6. 选择保存新请求的位置，然后选择保存。

    保存请求

编辑示例​

你可以随时编辑示例以删除敏感标记、更改状态代码或进行任何其他调整。

要编辑示例，请执行以下操作：

  1. 在边栏中选择收藏集。
  2. 选择一个请求，然后选择一个示例将其打开。
  3. 对示例请求或响应进行任何更改。
  4. 选择保存以保存示例。

要在尝试后编辑示例，请执行以下操作：

  1. 在边栏中选择收藏集。

  2. 选择一个请求，然后选择一个示例将其打开。

  3. 选择尝试在新选项卡中将示例作为请求打开。

    尝试示例

  4. 对新请求进行任何更改。

  5. 选择发送。

  6. 在响应窗格中，选择保存响应，然后选择更新示例。更新示例后，你将收到确认信息。

    更新示例

    新请求不会自动保存。

  7. 或者，你可以选择保存以将新请求保存到工作空间中的新集合或现有集合。

  8. 选择保存新请求的位置，然后选择保存。

    保存请求

复制一个例子​

复制示例以使用现有示例作为基础添加新示例。然后你可以编辑复制的示例以更改名称、状态代码或请求或响应的任何其他部分。

  1. 在边栏中选择收藏集。
  2. 更多操作图标 选择示例旁边的更多操作图标 ，然后选择复制。
  3. 对示例请求或响应进行任何更改。
  4. 选择保存以保存示例。

删除示例​

删除示例会将其从集合和关联的 API 文档中移除。你设置的任何模拟服务器都不能再使用该示例返回响应。

  1. 在边栏中选择收藏集。
  2. 更多操作图标 选择示例旁边的更多操作图标 ，然后选择删除。
  3. 选择删除进行确认。

在文档中使用示例​

Postman 会自动为你创建的每个集合 生成文档 。生成的文档包括已添加到集合中的 任何示例。 如果你编辑示例，文档会根据你的更改自动更新。

文档中的示例

示例为你的 API 提供更多详细信息和说明，并帮助你的团队共同开发 API。前端开发人员、后端开发人员和测试人员可以并行工作，使用文档中的示例作为指导或设置 模拟服务器 。

你可以 发布你的文档 ，使你的示例对世界上的任何人公开可用。

下一步​

你可以使用示例来设置模拟服务器并增强你的文档。