利用Sublime Text快速编写与本地预览Swagger/OpenAPI接口文档-sublime-PHP中文网

sublime text需插件组合实现openapi文档高效编写：yaml插件提供语法高亮，openapi specification插件启用结构感知与字段提示，sublimecodeintel支持智能补全，browser preview或redoc-cli实现预览，校验依赖openapi-cli命令行工具。

利用sublime text快速编写与本地预览swagger/openapi接口文档

Sublime Text 本身不支持 OpenAPI 文档的实时渲染，但通过插件组合 + 命令行工具，可以做到「写完即校验、保存即预览」——关键不是装一堆插件，而是选对三个角色：语法支持（YAML/JSON）、智能补全（SublimeCodeIntel）、预览入口（Browser Preview 或 redoc-cli）。

如何让 `openapi.yaml` 文件获得正确语法高亮和结构感知

默认打开 YAML 文件，Sublime 只识别为通用 YAML，不会触发 OpenAPI 特有字段提示（如 paths、components、securitySchemes）。必须手动绑定语言模式并启用 Schema 支持：

右键文件 → Change Language Mode → 选 YAML (OpenAPI)（需先安装 OpenAPI Specification 插件）
确保已安装 YAML 插件（提供基础高亮）和 AutoFileName（补全 $ref 路径时自动提示本地文件）

如果仍无字段提示，检查 SublimeCodeIntel 的 Settings - User 是否包含：

{
  "codeintel_language_settings": {
    "YAML": { "max_depth": 5 }
  },
  "codeintel_selected_catalogs": {
    "YAML": ["openapi"]
  }
}

`Ctrl+Shift+P` 里没有 `Preview in Browser` 怎么办

这不是 Sublime 原生功能，得靠 Markdown Preview 或 Browser Preview 插件提供入口。但注意：Markdown Preview 默认只处理 .md，要让它支持 .yaml 需额外配置：

Sublime Text Build Linux版

Sublime Text Linux x86-64 deb 安装包。官方也提供 rpm、tar.xz 和软件源安装方式。

下载

安装 Browser Preview（比 Markdown Preview 更轻量，且原生支持任意文本文件）
在 Preferences → Package Settings → Browser Preview → Settings 中添加：
```
"file_extensions": ["yaml", "yml", "json"]
```
用快捷键 Ctrl+Alt+P（默认）或右键 → Preview File in Browser，它会调用 redoc-cli 或本地服务渲染
若报错“command not found”，说明没装 redoc-cli：npm install -g redoc-cli，然后在命令面板运行 Redoc: Serve

为什么 `$ref` 指向 `./schemas/user.yaml` 在预览里不生效

Browser Preview 和 redoc-cli 默认不解析外部 YAML 引用——它们只读主文件，不递归加载 $ref。这不是 Sublime 的锅，是工具链限制：

用 openapi-cli bundle 合并所有引用：openapi-cli bundle openapi.yaml -o bundled.yaml，再预览这个合并后文件
或者改用 redoc-cli serve（它支持 --watch 和 --resolve 参数）：redoc-cli serve openapi.yaml --resolve
别指望插件自动做 resolve；Sublime 是编辑器，不是构建工具。想省事，就接受「编辑时用 Sublime，验证和预览时切到终端跑命令」这个分工

校验失败但 YAML 语法没错，常见硬伤在哪

YAML 解析通过 ≠ OpenAPI 合法。VSCode 或 openapi-cli validate 报的错，Sublime 里看不到，必须主动运行校验：

openapi-cli validate openapi.yaml 是最准的，它按 OAS 3.1 规范逐条检查
典型翻车点：enum 里写了数字 [200, 404]，必须改成字符串 ["200", "404"]
content 下直接写 schema: { type: string } 不合法，得包一层：schema: { type: string } → 正确写法是 schema: { type: string }（等等，不对——实际应为 schema: { type: "string" }，且必须嵌套在 content.<mime>.schema</mime> 下）
$ref 路径含 Windows 反斜杠 \ 或绝对路径 C:\...，一律失败，只认 POSIX 风格相对路径 ./components/responses/NotFound.yaml