# 编辑规范 (/zh/docs/specs/editing)
编辑规范有两种方式，可随时用页面标题栏中的**编辑器**在两者之间切换：**可视化**用卡片和字段，**代码**直接编辑 YAML 或 JSON。两者更改的是同一份文本。Echolot 保存的就是这份文本：可视化编辑只会更改你所编辑部分的那几行，因此你的注释、顺序和格式都不变，Git 差异也能准确显示改了什么。
要创建规范，请在边栏**规范**标题中选择 **+** › **新建规范**。Echolot 会在 `specs` 文件夹中写入一个标题为 `New API` 的 OpenAPI 3.1 文档，并在可视化编辑器中打开它。
## 可视化编辑器 [#the-visual-editor]
可视化编辑器中的字段会在你编辑完成时更改文档：按 ↩，或移到另一个字段。描述字段支持 Markdown，在其中按 ↩ 会另起一行；字段旁边的按钮会显示描述最终的呈现效果。
页面包含这些卡片：
| 卡片 | 编辑什么 |
| --- | --- |
| **概览** | API 的**标题**、**版本**和**描述**。 |
| **服务器** | 服务器的 URL 和描述。**添加服务器**添加一个；**−** 移除一个。没有服务器时，根据规范创建的请求以 `{{baseUrl}}` 开头，由你自己设置。 |
| **联系方式和许可证** | **显示**会展开联系人姓名、电子邮件和 URL、许可证及其 URL，以及服务条款。 |
| **端点** | 每个操作。**分组方式**按**路径**或**标签**列出它们（没有标签的归入**无标签**）。点按其中一个即可打开。 |
| **Schema** | 可复用的 Schema，正文和响应可以按名称引用。点按其中一个即可打开。 |
### 添加端点 [#adding-an-endpoint]
点按**端点**卡片中的**添加端点**。在**新建端点**表单中选择方法，输入路径（例如 `/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 [#adding-a-schema]
点按 **Schema** 卡片中的**添加 Schema**，给它起个名字，例如 `Product`，然后点按**添加**。打开的 Schema 有**名称**、**描述**和它的**属性**：每个属性都有名称、类型、**必填**和描述。**添加属性**添加一个。
Schema 会说明它在哪里被使用（**已在 3 处使用**，或**尚未使用**）。重命名它会更改对它的每一处引用。当 Schema 正在使用中时，**删除 Schema** 会先询问，因为那些引用将不再指向任何内容。不是普通对象的 Schema 在代码中描述和编辑：**在代码中显示**会带你过去。
### Swagger 2.0 [#swagger-20]
Swagger 2.0 文档可以在可视化编辑器中打开阅读，要编辑则在**代码**中进行。Echolot 设计的是 OpenAPI 3。
## 代码编辑器 [#the-code-editor]
将**编辑器**切换到**代码**，即可直接编辑 YAML 或 JSON。lint 会在你输入时稍作停顿后运行：错误和警告会在所在行加下划线，将指针停留在其上可查看消息。
将指针停留在 `$ref` 上可查看它指向什么；按住 ⌘ 点按则会跳转过去。指向另一个文件的引用会打开那个文件。规范所引用的文件总是在代码中打开。
当文本无法解析时，可视化编辑器会显示**可视化编辑器需要可解析的文档。**，以及行号和错误。**在代码中修正**会跳到那一行。
## 存储 [#saving]
无需手动存储。Echolot 会在每次更改后不久写入规范，并在你切换到另一个规范、离开页面或关闭窗口时写入。正在运行的该规范的模拟服务器会采用这些更改。
如果文件无法写入（例如它变成了只读），Echolot 会显示**无法存储规范**，并把你的编辑保留在编辑器中：
| 按钮 | 作用 |
| --- | --- |
| **重试** | 再次尝试写入文件。 |
| **存储副本…** | 把编辑写入你选择的文件。 |
| **放弃更改** | 回到磁盘上文件的样子。 |
| **继续编辑** | 关闭该消息。编辑会保留，页面也会停留在这个规范上，直到它们被存储。 |
## 撤销 [#undo]
**编辑 › 撤销**（⌘Z）可撤销任一编辑器中的编辑，**编辑 › 重做**（⇧⌘Z）可把它们恢复。每次可视化编辑算一步；输入文字则算一步，直到你停顿。撤销属于它所更改的规范：一旦打开另一个文件，就不会回溯到之前那个文件。
## 使用智能体 [#with-an-agent]
当你在**设置 › 智能体**中为外部[智能体](/docs/ai/agents)打开**规范**工具集后，它们就可以读取、写入并 lint 工作区的规范。