基于Sublime Text与OpenAPI 3.0的高效后端REST API规范编写-sublime-PHP中文网

sublime text 通过配置yaml、openapi specification和autofilename插件，结合openapi-cli校验、redoc-cli预览及自定义snippet，可高效编写规范的openapi文档。

基于sublime text与openapi 3.0的高效后端rest api规范编写

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，整个文档解析就会崩。

Wordpress REST API

OpenClaw技能，提供WordPress REST API命令行工具，支持通过原生HTTP处理文章、页面、分类、标签、用户及自定义请求。

下载

$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 的输出多看两眼，比写十行注释都管用。