# 从响应生成规范 (/zh/docs/specs/specs-from-traffic)

你往往先有请求，后有规范：别人导入的集合，或你在探索 API 时试过的调用。**从响应生成规范**会把它们变成 OpenAPI 文档。每个请求都成为一个操作，并依据它得到的最后一个响应来记录：路径和参数、发送的正文，以及响应，其中包含其正文的 JSON Schema 和一个示例。也可以添加到你已有的规范中，它只会补上缺少的内容。

## 记录一个文件夹 [#documenting-a-folder]

<Steps>
<Step>

发送你想记录的请求，让每个请求都有响应。例如在 Alpenglow 中，发送 **Catalog** 文件夹里的请求。

</Step>
<Step>

在“请求”边栏中右键点按该文件夹，选择**记录到 OpenAPI 规范…**。要记录整个工作区，请在“规范”边栏中选择 **+** › **从响应新建规范…**，在空的“规范”页面上选择**从响应生成…**，或在命令面板中选择**从响应新建规范…**。

</Step>
<Step>

在**记录到 OpenAPI 规范**表单中检查各项选择：

| 选项 | 含义 |
| --- | --- |
| **请求** | **整个工作区**，或某个文件夹。其子文件夹中的请求也包含在内。 |
| **规范** | **新建规范**，或工作区中要添加内容的某个规范。已经遵循某个规范的文件夹会添加到那个规范。 |
| **标题** | 新规范的标题。初始为文件夹的名称，或工作区的名称。 |
| **将“文件夹”链接到规范** | 默认开启。文件夹中的请求随后会遵循它们所转成的操作，因此之后对规范的更改可以应用到这些请求上。 |

</Step>
<Step>

点按**记录**。表单会说明发生了什么，然后点按**打开规范**即可打开结果。

</Step>
</Steps>

<Shot id="specs-from-responses" alt="记录 Catalog 文件夹之后的“记录到 OpenAPI 规范”表单：新操作、被排除在外的请求及其原因，以及“打开规范”按钮" />

## 你会得到什么 [#what-you-get]

结果列出：

| 标题 | 含义 |
| --- | --- |
| **新操作** | 规范中原本没有的操作，例如 `GET /products/{sku}`。 |
| **已添加响应** | 规范中原有、现在又记录了另一个响应的操作，例如 `404`。 |
| **已记录** | 规范已按其应答的样子记录的操作。没有任何更改。 |
| **未包含** | 未被记录的请求，每个都附有原因。 |

它还会说明现在有多少个请求遵循其操作，以及（如果有）lint 在结果中发现了多少个错误。

每个操作包含的内容：

- **路径**，采用 OpenAPI 的形式：来自变量的路径段会变成路径参数，并用发送的值来记录。URL 的服务器部分不计入路径。
- 请求设置的**查询参数和标头**。
- **请求正文**和**响应**，其中有根据正文生成的 JSON Schema 和一个示例。过大的示例会被省略而保留 Schema；较长的数组在示例中只保留几项。
- **请求的名称**作为操作的摘要，**它所在的子文件夹**作为操作的标签。
- **请求的认证**作为安全方案。对于 OpenAPI 没有对应方案的认证（使用设备代码授权的 OAuth 2），会有一条说明。

机密会被遮蔽：机密变量，以及看起来像机密的键（令牌、密码、密钥）下的值，在示例中显示为 `••••••`。

## 添加到已有的规范 [#adding-to-a-spec-you-have]

在**规范**下选择该规范。Echolot 只会添加缺少的内容：它尚未提及的操作、响应、Schema 和安全方案。规范中已有的内容保持原样。Swagger 2.0 的规范无法添加内容；只有 OpenAPI 3 文档可以。

## 从历史记录中记录单个响应 [#documenting-single-responses-from-history]

在[历史记录](/docs/workspaces/history)中，右键点按得到了响应的 HTTP 交换，选择**添加到 OpenAPI 规范…**。同一个表单会打开，针对的是那一个响应。这对只见过一次的响应很方便，例如某个错误。

## 哪些内容不会包含 [#what-is-left-out]

- 不是 HTTP 的请求（GraphQL、gRPC、WebSocket 等）：OpenAPI 中只记录 HTTP 请求。
- 还没有响应的请求：请先发送它们。
- 发送失败、没有得到任何响应的请求。
- 位于遵循自己规范的子文件夹中的请求。

## 保持最新 [#keep-it-current]

文件夹一旦遵循规范，规范就是契约。在“规范”页面中编辑它，并用<strong>检查“文件夹”的更改…</strong>把更改应用到请求上。参见[遵循规范的请求](/docs/specs#requests-that-follow-the-spec)。你也可以把规范的响应交给[模拟服务器](/docs/mocks)，让前端据此开发。

当**规范**工具集开启时，智能体可以通过 `add_to_spec` 工具完成同样的事：参见[智能体](/docs/ai/agents)。