需安装OpenAPI Specification插件实现语法高亮与校验：通过Package Control安装后手动设置语法类型，配置SublimeLinter调用官方JSON Schema实时校验，并正确管理片段作用域与路径避免冲突。
安装 OpenAPI 语法高亮插件
Sublime Text 默认不识别 openapi.yaml 或 swagger.json，直接打开只会用通用 YAML/JSON 规则着色，关键字段（如 paths、components、schema）没特殊标记，写错缩进或漏字段很难一眼发现。
推荐装 OpenAPI Specification 插件（作者：bradleybossard），它支持 OpenAPI 3.0+ 和 Swagger 2.0，语法校验比纯高亮更进一步：
- 通过 Package Control 安装后，打开
.yaml文件 → 右下角点击语法类型 → 选OpenAPI Specification - 若文件后缀不是
.yaml/.yml（比如叫api.oas3），需手动关联：菜单View → Syntax → OpenAPI Specification，再执行Preferences → Settings – Syntax Specific，加一行："extensions": ["oas3", "swagger"] - 别装错同名但维护停滞的旧插件（如
SwaggerSpec），它只支持 Swagger 2.0 且不兼容 Sublime Text 4
启用 JSON Schema 校验（避免手写错误）
光有语法高亮不够，required 写成 requied、type: string 漏了引号、responses 下错层——这些都不会报错，但会导致生成文档失败或工具解析中断。
得让 Sublime 调用官方 OpenAPI Schema 做实时校验：
- 装
SublimeLinter+SublimeLinter-contrib-jsonschema插件 - 在项目根目录放
.jsonschema文件（内容为 OpenAPI 3.1 官方 Schema URL：https://spec.openapis.org/oas/3.1/schema），或直接在 Sublime 的SublimeLinter.sublime-settings里配"jsonschema": {"schema": "https://spec.openapis.org/oas/3.1/schema"} - 注意：YAML 文件必须以
openapi: 3.1.0开头，否则校验器会跳过；Swagger 2.0 用户得换用https://swagger.io/v2/schema.json
补全和片段（Snippet）怎么设才不冲突
Sublime 自带的 YAML 片段和 OpenAPI 插件的片段可能打架——比如敲 pa 按 Tab，出来的是 parameters: 还是普通 YAML 的 path:？顺序错了就卡住。
解决方法很简单，靠优先级控制：
- 插件自带的片段一般放在
Packages/OpenAPI Specification/snippets/，不用动 - 自己写的常用片段（如快速插入
securitySchemes）要放Packages/User/openapi-snippets/，并确保文件名以.sublime-snippet结尾 - 在片段 XML 里显式指定
scope="source.openapi"（不是source.yaml），这样只在 OpenAPI 语法模式下触发 - 别把 OpenAPI 片段塞进全局
YAML.sublime-snippets，否则所有 .yaml 文件都会弹，干扰日常配置文件编辑
为什么改了设置不生效？常见掉坑点
最常遇到的不是“不会配”，而是“配了但没反应”——多半是路径、作用域或缓存问题。
- 插件安装后没重启 Sublime？某些插件（尤其是带 LSP 支持的）需要完全退出再重开
- 文件已打开时切换语法模式，校验器可能不自动启动；关掉重开，或手动触发
SublimeLinter: Lint This View - 用了
Project.sublime-project配置？检查里面有没有覆盖settings里的syntax或file_exclude_patterns，后者可能把*.yaml给 exclude 掉了 - Mac 上用 Homebrew 装的 Sublime？插件路径在
~/Library/Application Support/Sublime Text/Packages/，别去/opt/homebrew/...目录下瞎找
OpenAPI 文档本质是代码，不是静态文本。语法支持只是第一道防线，真正容易被忽略的是：Schema 校验依赖网络拉取远程 JSON Schema，离线环境或公司内网得提前下载本地副本并指向 file:// 路径——否则 lint 就是静默失效。
