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

sublime text 本身不支持 swagger/openapi 文档实时预览，但可通过插件组合高效编写：必须同时安装 yaml 和 openapi specification 插件以实现语法高亮、结构校验与关键字补全；autofilename 支持 $ref 路径补全；sublimecodeintel 需配置 yaml + openapi catalog 才能提供深度补全；本地预览依赖 redoc-cli 或 swagger-cli 等外部工具，且 $ref 路径须小写、相对、以 ./ 开头。

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

Sublime Text 本身不支持 Swagger / OpenAPI 文档的实时预览，但能高效编写——关键在插件组合与工作流设计，不是靠“一键预览”幻想。

YAML 插件 + OpenAPI Specification 插件必须装齐

只装 YAML 高亮插件，openapi.yaml 文件里写错缩进或漏冒号，你根本看不到红色波浪线；只装 OpenAPI Specification 插件但没 YAML 支持，连基本语法都识别不了。二者缺一不可：

YAML 插件提供基础语法高亮、缩进对齐、折叠支持
OpenAPI Specification 插件提供 paths、components、schema 等关键字补全和结构校验（注意：它不做语义验证，比如不会告诉你 required 字段是否真在 properties 里）
AutoFileName 插件能自动补全 $ref 路径，比如输入 $ref: "./ 后回车，直接列出当前目录下所有 .yaml 文件

SublimeCodeIntel 配置必须加 `YAML` 和 `openapi` catalog

默认情况下 SublimeCodeIntel 对 YAML 文件只做基础补全，type: object 后敲 prop 不会提示 properties。必须手动改配置：

Sublime Text Build Linux版

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

下载

打开 Preferences → Package Settings → SublimeCodeIntel → Settings - User

填入以下内容（注意是 JSON 格式，别漏逗号）：

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

重启 Sublime 或执行 SublimeCodeIntel: Rebuild Index 命令（Ctrl+Shift+P 输入）
不配 openapi catalog，components: 下面敲 schemas: 就没补全；配了但没设 max_depth，嵌套三层后补全就失效

本地预览只能靠 CLI 工具，别指望 Sublime 内置浏览器

Sublime 没有内置 Web 渲染引擎，所谓“预览”只能靠外部工具生成静态页再用浏览器打开。实测最轻量闭环是：

用 redoc-cli（推荐）：npm install -g redoc-cli，然后在 openapi.yaml 所在目录运行 redoc-cli serve openapi.yaml，自动打开 http://127.0.0.1:8080
用 swagger-cli 验证语法：swagger-cli validate openapi.yaml，报错会明确指出哪一行哪个字段不合法（比如 enum 值不是字符串数组）
Browser Preview 插件可绑定快捷键自动刷新页面，但需提前在 redoc-cli 启动状态下使用，否则只是打开一个空白页
别试 openapi-cli 的 preview 命令——它依赖 Node.js 且常因版本冲突失败，redoc-cli 更稳定

`$ref` 引用本地文件时路径必须相对且小写

这是最常打断编辑流的坑：你写了 $ref: './schemas/User.yaml'，Sublime 不报错，redoc-cli 却说 file not found。原因不是路径错，而是：

redoc-cli 和 swagger-cli 默认只识别小写后缀，User.YAML 或 User.Yaml 都不行，必须是 User.yaml
路径必须以 ./ 开头，不能是 schemas/User.yaml（无前缀会被当绝对路径处理）
不能跨根目录引用，$ref: '../common.yaml' 在子目录下会失败，得用 ../common.yaml 并确保 CLI 当前工作目录是项目根
Sublime 的 AutoFileName 插件补全路径时默认带 ./，但大小写不自动修正，得自己检查