Echolot规范
在工作区中保存 OpenAPI 文档和 .proto 文件，查看它们的大纲和问题，并将它们转换为请求。
“规范”页面用于设计并保存 API 的契约：OpenAPI 文档（OpenAPI 3.0 和 3.1，以及 Swagger 2.0）和 gRPC 服务的 .proto 文件。Echolot 会在你编辑时检查规范，把它转换为与之保持同步的请求，并在 API 出现之前将它作为模拟服务器提供服务。
在边栏的模块切换器中选择规范，或按 ⌘3，即可打开。
工作区中的规范
规范是工作区 specs 文件夹中的文件，因此会和其他一切一起进入 Git。Alpenglow 示例有三个：alpenglow.yaml（商店的 OpenAPI 文档）、shop.graphql 和 inventory.proto。“规范”页面在规范下列出 OpenAPI 文档，在 Proto 文件下列出 .proto 文件。文件夹中的 GraphQL Schema 供 GraphQL 请求使用，不在这里列出。
边栏规范标题中的 + 用于添加：
| 项目 | 作用 |
|---|---|
| 新建规范 | 创建一个标题为 New API 的 OpenAPI 3.1 文档，并在可视化编辑器中打开。 |
| 从响应新建规范… | 根据你发送过的请求和得到的响应写出规范。参见从响应生成规范。 |
| 添加规范文件… | 把 Mac 上的 OpenAPI 或 Swagger 文档（YAML 或 JSON）拷贝到 specs 文件夹。 |
| 新建 Proto 文件 | 从一个简单的示例服务创建 .proto 文件。参见 .proto 文件。 |
| 添加 Proto 文件… | 把 .proto 文件拷贝到 specs 文件夹。 |
用文件 › 导入…导入 OpenAPI 文档则不同：它根据文档创建请求，而不是创建可供编辑的规范。
右键点按规范可选择生成请求、在访达中显示、导出（JSON 格式…或YAML 格式…）和删除…。删除前会先询问，并把文件移到废纸篓；它所引用的文件和基于它的模拟服务器都会保留。
大纲
点按规范即可打开。在列表下方，边栏显示它的大纲：
- 概览，即标题、版本和描述。
- 端点，每个操作及其方法和路径。已弃用的带删除线。将指针停留在其上可查看摘要。
- SCHEMA，可复用的 Schema。
- 文件，当规范引用其他文件时（参见拆分到多个文件的规范）。
点按某个条目即可打开：在可视化编辑器中，对应的卡片会打开并滚动到视野内；在代码中，编辑器会跳到它所在的行。
可视化和代码
页面标题栏中的编辑器开关决定如何查看打开的规范：
- 可视化：概览、服务器、端点和 Schema 的卡片，用字段和菜单编辑。
- 代码：YAML 或 JSON 格式的文档，带行号。
两者编辑的是同一份文本，Echolot 会在每次更改后不久存储它。编辑规范对两者都有介绍。
问题
Echolot 会在你编辑时对规范做 lint 检查。编辑器上方的栏显示没有问题，或错误和警告的数量。边栏中打开的规范旁边也会显示红色的错误数。
点按它可查看列表：先是错误，然后是警告和提示，每项都带有行号。选择其中一项可跳到那一行。列表为空时，会说明文档符合 OpenAPI 规范，且每个引用都能解析。
lint 检查的内容包括：
- Echolot 能读取的
openapi版本、带有标题和版本的info，以及以/开头的路径。 - 出现在路径中且标记为
required: true的路径参数，以及没有重复定义的参数。 - 每个响应都有描述，且每个操作 ID 只使用一次。
- 在顶部声明的标签、已定义的安全方案、带
items的数组，以及带值的枚举。 - 指向实际内容的引用，在本文件中，或在
specs里的另一个文件中。 - 没有
servers：此时根据规范创建的请求以{{baseUrl}}开头，由你自己设置。
命令行工具在 CI 中运行相同的 lint：参见 echolot spec。
拆分到多个文件的规范
规范可以用 $ref 引入其他文件的部分内容，例如 $ref: schemas/pet.yaml#/Pet。这些文件必须位于工作区的 specs 文件夹内。边栏在文件下列出它们：点按其中一个，即可在代码中打开。在代码编辑器中，将指针停留在 $ref 上可查看它指向什么，按住 ⌘ 点按则会跳转过去，无论在本文件还是另一个文件中。
凡是用到规范的地方，Echolot 都会把各部分合在一起读取：lint、生成请求、模拟服务器。导出规范时，它引用的文件会写入你存储的那一个文件。
导出
编辑器上方栏中的导出（导出为 YAML…或导出为 JSON…）会把规范存储为工作区之外的一个文件，它引用的文件会写入其中。未存储的编辑会先存储，因此导出的就是编辑器显示的内容。
遵循规范的请求
编辑器上方栏中的生成请求会创建一个以规范命名的文件夹，其中为每个端点创建一个请求，并打开第一个。该文件夹会遵循规范：规范更改时，你可以把更改应用到它的请求上，而不会丢失你在请求中所做的编辑。
文件夹一旦遵循规范，该按钮就变成请求，这是一个菜单，其中为每个遵循规范的文件夹提供检查“文件夹”的更改…，另有再生成一个文件夹。检查会打开 OpenAPI 同步，列出规范中新增、规范中已更改和已从规范中移除的内容。勾选你想要的更改并点按应用 1 项更改（或应用 3 项更改，依此类推）。你的编辑始终会保留；当你和规范更改了同一处时，保留你的。某个操作被移除后，它的请求会移到废纸篓，除非你编辑过它：那样它会保留，但不再遵循规范。取消链接会让文件夹不再遵循规范，并保持其请求不变。
文件夹也可以遵循工作区之外的规范，即一个文件或一个 URL：在“请求”边栏中右键点按该文件夹，选择链接到 OpenAPI 规范…。命令行工具用 echolot spec check 和 echolot spec apply 检查并应用更改。