Echolot编辑规范
在可视化编辑器或 YAML 中设计 OpenAPI 文档，输入时即时 lint 检查，并支持存储和撤销。
编辑规范有两种方式，可随时用页面标题栏中的编辑器在两者之间切换：可视化用卡片和字段，代码直接编辑 YAML 或 JSON。两者更改的是同一份文本。Echolot 保存的就是这份文本：可视化编辑只会更改你所编辑部分的那几行，因此你的注释、顺序和格式都不变，Git 差异也能准确显示改了什么。
要创建规范，请在边栏规范标题中选择 + › 新建规范。Echolot 会在 specs 文件夹中写入一个标题为 New API 的 OpenAPI 3.1 文档，并在可视化编辑器中打开它。
可视化编辑器
可视化编辑器中的字段会在你编辑完成时更改文档：按 ↩，或移到另一个字段。描述字段支持 Markdown，在其中按 ↩ 会另起一行；字段旁边的按钮会显示描述最终的呈现效果。
页面包含这些卡片：
| 卡片 | 编辑什么 |
|---|---|
| 概览 | API 的标题、版本和描述。 |
| 服务器 | 服务器的 URL 和描述。添加服务器添加一个；− 移除一个。没有服务器时，根据规范创建的请求以 {{baseUrl}} 开头，由你自己设置。 |
| 联系方式和许可证 | 显示会展开联系人姓名、电子邮件和 URL、许可证及其 URL，以及服务条款。 |
| 端点 | 每个操作。分组方式按路径或标签列出它们（没有标签的归入无标签）。点按其中一个即可打开。 |
| Schema | 可复用的 Schema，正文和响应可以按名称引用。点按其中一个即可打开。 |
添加端点
点按端点卡片中的添加端点。在新建端点表单中选择方法，输入路径（例如 /products/{sku}），还可以输入摘要和标签，然后点按添加端点。Echolot 会为你定义路径的参数，并添加一个正文和一个成功响应作为起点。已经存在的方法和路径组合会被拒绝。
打开的端点包含：
| 部分 | 编辑什么 |
|---|---|
| 端点 | 方法和路径。更改它们会移动该操作。 |
| 摘要、描述 | 简短的名称，例如 List products，以及它做什么、需要什么、返回什么。 |
| 操作 ID、标签 | 代码生成器使用的 ID，以及用逗号分隔的标签。 |
| 已弃用 | 将该操作标记为已弃用。 |
| 参数 | 每个参数的名称、位置（位置：path、query、header 或 cookie）、类型、必填和描述。添加参数添加一个。当路径中出现了未定义的参数名时，会出现类似添加 {sku} 的按钮来定义它。标有整个路径的参数对该路径的每个方法都有效。 |
| 请求正文 | 添加正文添加一个 JSON 正文；每种媒体类型都有一个 Schema，正文可以设为必填。移除正文将其去掉。 |
| 响应 | 每个状态码一行，带有描述；在添加正文之后，还有它的媒体类型和 Schema。添加响应会添加下一个尚未使用的常见状态码（200、201、204、400、401、403、404、409、422、500，然后是 default）。编辑状态码即可更改它。一个操作至少需要一个响应。 |
参数、正文或属性的类型是一个菜单：可复用的 Schema、string、integer、number、boolean 或 object，以及这些类型中任一个的数组，元素为，或无。菜单无法表达的 Schema 会按其书写原样显示，并一直保留，直到你选择别的类型。
打开的端点底部是 lint 在其中发现的第一个问题（将指针停留在其上可查看全部问题），以及三个按钮：打开请求（当有请求遵循此操作时）、在代码中显示和删除端点。
添加 Schema
点按 Schema 卡片中的添加 Schema，给它起个名字，例如 Product，然后点按添加。打开的 Schema 有名称、描述和它的属性：每个属性都有名称、类型、必填和描述。添加属性添加一个。
Schema 会说明它在哪里被使用（已在 3 处使用，或尚未使用）。重命名它会更改对它的每一处引用。当 Schema 正在使用中时，删除 Schema 会先询问，因为那些引用将不再指向任何内容。不是普通对象的 Schema 在代码中描述和编辑：在代码中显示会带你过去。
Swagger 2.0
Swagger 2.0 文档可以在可视化编辑器中打开阅读，要编辑则在代码中进行。Echolot 设计的是 OpenAPI 3。
代码编辑器
将编辑器切换到代码，即可直接编辑 YAML 或 JSON。lint 会在你输入时稍作停顿后运行：错误和警告会在所在行加下划线，将指针停留在其上可查看消息。
将指针停留在 $ref 上可查看它指向什么；按住 ⌘ 点按则会跳转过去。指向另一个文件的引用会打开那个文件。规范所引用的文件总是在代码中打开。
当文本无法解析时，可视化编辑器会显示可视化编辑器需要可解析的文档。，以及行号和错误。在代码中修正会跳到那一行。
存储
无需手动存储。Echolot 会在每次更改后不久写入规范，并在你切换到另一个规范、离开页面或关闭窗口时写入。正在运行的该规范的模拟服务器会采用这些更改。
如果文件无法写入（例如它变成了只读），Echolot 会显示无法存储规范，并把你的编辑保留在编辑器中：
| 按钮 | 作用 |
|---|---|
| 重试 | 再次尝试写入文件。 |
| 存储副本… | 把编辑写入你选择的文件。 |
| 放弃更改 | 回到磁盘上文件的样子。 |
| 继续编辑 | 关闭该消息。编辑会保留，页面也会停留在这个规范上，直到它们被存储。 |
撤销
编辑 › 撤销（⌘Z）可撤销任一编辑器中的编辑，编辑 › 重做（⇧⌘Z）可把它们恢复。每次可视化编辑算一步；输入文字则算一步，直到你停顿。撤销属于它所更改的规范：一旦打开另一个文件，就不会回溯到之前那个文件。
使用智能体
当你在设置 › 智能体中为外部智能体打开规范工具集后，它们就可以读取、写入并 lint 工作区的规范。