# 规范 (/zh/docs/specs)

“规范”页面用于设计并保存 API 的契约：OpenAPI 文档（OpenAPI 3.0 和 3.1，以及 Swagger 2.0）和 gRPC 服务的 `.proto` 文件。Echolot 会在你编辑时检查规范，把它转换为与之保持同步的请求，并在 API 出现之前将它作为[模拟服务器](/docs/mocks)提供服务。

在边栏的模块切换器中选择**规范**，或按 <kbd>⌘</kbd><kbd>3</kbd>，即可打开。

<Shot id="specs-page" alt="“规范”页面，alpenglow.yaml 在可视化编辑器中打开：边栏列出该规范及其端点和 Schema 的大纲；页面显示“概览”“服务器”和“端点”卡片" />

## 工作区中的规范 [#specs-in-the-workspace]

规范是工作区 `specs` 文件夹中的文件，因此会和其他一切一起进入 Git。Alpenglow 示例有三个：`alpenglow.yaml`（商店的 OpenAPI 文档）、`shop.graphql` 和 `inventory.proto`。“规范”页面在**规范**下列出 OpenAPI 文档，在 **Proto 文件**下列出 `.proto` 文件。文件夹中的 GraphQL Schema 供 [GraphQL 请求](/docs/requests/graphql)使用，不在这里列出。

边栏**规范**标题中的 **+** 用于添加：

| 项目 | 作用 |
| --- | --- |
| **新建规范** | 创建一个标题为 `New API` 的 OpenAPI 3.1 文档，并在可视化编辑器中打开。 |
| **从响应新建规范…** | 根据你发送过的请求和得到的响应写出规范。参见[从响应生成规范](/docs/specs/specs-from-traffic)。 |
| **添加规范文件…** | 把 Mac 上的 OpenAPI 或 Swagger 文档（YAML 或 JSON）拷贝到 `specs` 文件夹。 |
| **新建 Proto 文件** | 从一个简单的示例服务创建 `.proto` 文件。参见 [.proto 文件](/docs/specs/proto-files)。 |
| **添加 Proto 文件…** | 把 `.proto` 文件拷贝到 `specs` 文件夹。 |

用**文件 › 导入…**[导入](/docs/get-started/importing) OpenAPI 文档则不同：它根据文档创建请求，而不是创建可供编辑的规范。

右键点按规范可选择**生成请求**、**在访达中显示**、**导出**（**JSON 格式…**或**YAML 格式…**）和**删除…**。删除前会先询问，并把文件移到废纸篓；它所引用的文件和基于它的模拟服务器都会保留。

## 大纲 [#the-outline]

点按规范即可打开。在列表下方，边栏显示它的大纲：

- **概览**，即标题、版本和描述。
- **端点**，每个操作及其方法和路径。已弃用的带删除线。将指针停留在其上可查看摘要。
- **SCHEMA**，可复用的 Schema。
- **文件**，当规范引用其他文件时（参见[拆分到多个文件的规范](#specs-split-across-files)）。

点按某个条目即可打开：在可视化编辑器中，对应的卡片会打开并滚动到视野内；在代码中，编辑器会跳到它所在的行。

## 可视化和代码 [#visual-and-code]

页面标题栏中的**编辑器**开关决定如何查看打开的规范：

- **可视化**：概览、服务器、端点和 Schema 的卡片，用字段和菜单编辑。
- **代码**：YAML 或 JSON 格式的文档，带行号。

两者编辑的是同一份文本，Echolot 会在每次更改后不久存储它。[编辑规范](/docs/specs/editing)对两者都有介绍。

## 问题 [#problems]

Echolot 会在你编辑时对规范做 lint 检查。编辑器上方的栏显示**没有问题**，或错误和警告的数量。边栏中打开的规范旁边也会显示红色的错误数。

<Shot id="specs-problems" alt="规范上方的“问题”弹出窗口：错误和警告，每项都带有消息和行号" />

点按它可查看列表：先是错误，然后是警告和提示，每项都带有行号。选择其中一项可跳到那一行。列表为空时，会说明文档符合 OpenAPI 规范，且每个引用都能解析。

lint 检查的内容包括：

- Echolot 能读取的 `openapi` 版本、带有标题和版本的 `info`，以及以 `/` 开头的路径。
- 出现在路径中且标记为 `required: true` 的路径参数，以及没有重复定义的参数。
- 每个响应都有描述，且每个操作 ID 只使用一次。
- 在顶部声明的标签、已定义的安全方案、带 `items` 的数组，以及带值的枚举。
- 指向实际内容的引用，在本文件中，或在 `specs` 里的另一个文件中。
- 没有 `servers`：此时根据规范创建的请求以 `{{baseUrl}}` 开头，由你自己设置。

命令行工具在 CI 中运行相同的 lint：参见 [echolot spec](/docs/cli/spec)。

## 拆分到多个文件的规范 [#specs-split-across-files]

规范可以用 `$ref` 引入其他文件的部分内容，例如 `$ref: schemas/pet.yaml#/Pet`。这些文件必须位于工作区的 `specs` 文件夹内。边栏在**文件**下列出它们：点按其中一个，即可在**代码**中打开。在代码编辑器中，将指针停留在 `$ref` 上可查看它指向什么，按住 <kbd>⌘</kbd> 点按则会跳转过去，无论在本文件还是另一个文件中。

凡是用到规范的地方，Echolot 都会把各部分合在一起读取：lint、生成请求、模拟服务器。导出规范时，它引用的文件会写入你存储的那一个文件。

## 导出 [#exporting]

编辑器上方栏中的**导出**（**导出为 YAML…**或**导出为 JSON…**）会把规范存储为工作区之外的一个文件，它引用的文件会写入其中。未存储的编辑会先存储，因此导出的就是编辑器显示的内容。

## 遵循规范的请求 [#requests-that-follow-the-spec]

编辑器上方栏中的**生成请求**会创建一个以规范命名的文件夹，其中为每个端点创建一个请求，并打开第一个。该文件夹会遵循规范：规范更改时，你可以把更改应用到它的请求上，而不会丢失你在请求中所做的编辑。

文件夹一旦遵循规范，该按钮就变成**请求**，这是一个菜单，其中为每个遵循规范的文件夹提供**检查“文件夹”的更改…**，另有**再生成一个文件夹**。检查会打开 **OpenAPI 同步**，列出**规范中新增**、**规范中已更改**和**已从规范中移除**的内容。勾选你想要的更改并点按**应用 1 项更改**（或**应用 3 项更改**，依此类推）。你的编辑始终会保留；当你和规范更改了同一处时，保留你的。某个操作被移除后，它的请求会移到废纸篓，除非你编辑过它：那样它会保留，但不再遵循规范。**取消链接**会让文件夹不再遵循规范，并保持其请求不变。

文件夹也可以遵循工作区之外的规范，即一个文件或一个 URL：在“请求”边栏中右键点按该文件夹，选择**链接到 OpenAPI 规范…**。命令行工具用 `echolot spec check` 和 `echolot spec apply` 检查并应用更改。