Sublime Text 通过配置YAML、OpenAPI Specification和AutoFileName插件，结合openapi-cli校验、redoc-cli预览及自定义snippet，可高效编写规范的OpenAPI文档。
Sublime Text 本身不支持 OpenAPI 文档的实时校验或渲染，但只要插件配得准、工作流理得清，写 openapi.yaml 的效率不输专业 IDE，甚至更轻快。
YAML 插件装不全，openapi.yaml 就会漏高亮和补全
Sublime 默认不识别 YAML 语法，更不会懂 paths、components 这些 OpenAPI 关键字。没装对插件，写到一半发现缩进报红、字段没提示，纯靠手敲容易拼错 in: path 写成 in: Path ——OpenAPI 规范大小写敏感，这种错误本地看不出来，但 openapi-cli validate 一跑就报 ValidationError: 'Path' is not one of ['query', 'path', 'header', 'cookie']。
- 必须装
YAML插件（提供基础语法高亮和缩进） - 必须装
OpenAPI Specification插件（识别openapi: 3.0.0开头，提供关键字补全、路径模板 snippet） - 建议装
AutoFileName（在$ref: '#/components/schemas/User'里按Ctrl+Space能自动列出已定义的 schema 名）
openapi-cli 校验失败常见于 $ref 路径和缩进混用
很多人用 Sublime 写完直接丢给 CI，结果构建失败。最常卡在两处：$ref 指向内部组件时路径写错，或者 YAML 缩进用 Tab 和空格混了——YAML 对缩进极其严格，哪怕只有一行用 Tab，整个文档解析就会崩。
-
$ref指向同文件内组件，必须用#/components/schemas/User，不能漏掉开头的#，也不能写成./components/schemas/User - 所有缩进统一用 2 个空格（OpenAPI 官方示例默认），Sublime 设置：菜单 → Preferences → Settings → 加入
"tab_size": 2, "translate_tabs_to_spaces": true - 校验命令别只跑一次：
openapi-cli validate openapi.yaml && openapi-cli bundle openapi.yaml -o bundled.yaml，后者能提前暴露跨文件引用问题
用 snippet 快速生成 /users/{id} 这类带路径参数的结构
手动敲 parameters 块又容易忘 required: true 或漏 schema，Sublime 的 snippet 能省掉重复劳动。比如定义一个 GET /users/{id}，你只需要输入 opgetpath + Tab，就能展开为完整结构，字段名、位置、是否必填都预设好了。
- Snippet 文件存放在
Packages/User/openapi-get-path.sublime-snippet - 内容核心是：
"in": "path", "name": "${1:id}", "required": true, "schema": { "type": "${2:integer}" } - 注意
${1:id}这种占位符，Tab 键可跳转编辑，比复制粘贴改名快得多
预览文档别依赖在线 Editor，本地 redoc-cli 更可控
把 openapi.yaml 拖进 Swagger Editor 看起来方便，但它不校验、不报错，还可能因网络加载失败。真正联调前需要确认文档语义无歧义，比如 404 响应有没有定义 content，POST /users 的 requestBody 是否标记了 required: true ——这些细节在线工具根本不检查。
- 装
redoc-cli：npm install -g redoc-cli - 启动本地服务：
redoc-cli serve openapi.yaml，自动打开浏览器，且保存文件后页面热刷新 - 关键好处：如果
$ref错了或 schema 缺字段，redoc 启动时直接报错退出，不让你糊弄过去
最难的不是写对某个字段，而是让所有协作方——后端、前端、测试——都基于同一份 YAML 文件生成各自代码或 Mock 数据。一旦 openapi.yaml 里出现模糊描述（比如 response 里只写 type: object 不定义 properties），后续所有自动化环节都会开始猜，猜错了就得返工。所以每次提交前，盯着 openapi-cli bundle 的输出多看两眼，比写十行注释都管用。
