VSCode配置OpenAPI/Swagger文档编辑插件推荐指南【详细】-VSCode-PHP中文网

vscode 1.77+ 原生支持 openapi v3.x 预览，无需插件即可点击 preview 按钮；但自动补全、$ref 跳转、enum 校验和错误高亮需手动配置 red hat yaml 插件及 v3.1 schema 绑定，并确保文件后缀为 .yaml/.yml/.json、首行为 openapi:、语言模式设为 openapi specification。

vscode配置openapi/swagger文档编辑插件推荐指南【详细】

VSCode 1.77+ 原生支持 OpenAPI v3.x 预览，不装插件也能点开 Preview 按钮；但想获得自动补全、$ref 跳转、enum 校验和错误高亮，必须配 Red Hat YAML + 正确的 Schema 绑定——不是装了就生效，而是每一步都卡在细节上。

为什么预览按钮不出现或点开是空白

根本不是插件没装对，而是 VSCode 没把当前文件识别为 OpenAPI 模式。它只认三种后缀：.yaml、.yml、.json，且内容第一行必须是 openapi:（不能是 swagger:）。

右键文件 → Change Language Mode → 选 OpenAPI Specification（不是 YAML 或 JSON）
点击右下角弹出的 Configure File Association for '.yaml'，输入 openapi 回车，这样所有 .yaml 文件默认走 OpenAPI 模式
如果仍不显示预览按钮，按 Ctrl+Shift+P 输入命令 OpenAPI: Open Preview to the Side 手动唤出

自动补全失效或 enum 报错：Schema 绑定必须手动配

Red Hat YAML 插件本身不自动关联 OpenAPI Schema。不配置，就只有基础 YAML 补全，没有字段提示、必填校验、$ref 跳转这些能力。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

打开 settings.json（设置 → 右上角“打开设置(JSON)”）

加这段（注意路径是 v3.1/schema.json，不是 v3.0）：

"yaml.schemas": {
  "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": ["*.yaml", "*.yml"]
}

改完保存，重新打开文件；再看问题面板（Cmd+Shift+M）有没有红色波浪线
enum 必须写字符串：enum: ["ACTIVE", "INACTIVE"] 合法，enum: [1, 2] 直接报错

`$ref` 总报 file not found 的真实原因

$ref 在 VSCode 里不是“能读 YAML 就行”，它只认两种情况：引用目标是 JSON，或者目标 YAML 文件显式声明了 openapi: 版本号。

所有被 $ref 引用的 YAML 文件（如 ./components/schemas/User.yaml）第一行必须是 openapi: 3.1.0 或 openapi: 3.0.3
路径只能用正斜杠 /，Windows 上写 .\components\schemas\User.yaml 必然失败
不支持 $ref: 'https://... —— VSCode 不发起网络请求校验远程地址
检查文件是否真实存在：隐藏后缀（如 User.yaml.txt）或大小写错误（user.yaml vs User.yaml）在 macOS/Linux 下也会触发 file not found

别装 Swagger Viewer 或 OpenAPI Preview 这类插件

它们要么已停更，要么只支持 Swagger 2.0（swagger: "2.0"），打开 openapi: 3.1.0 文件会直接报错或空白。VSCode 自带的 OpenAPI Editor 功能（由 Red Hat 提供，已内置）原生支持 v3.0.0 及以上，点击右上角 Preview 按钮即可渲染交互式文档。

确认 VSCode 版本 ≥ 1.77（低于此版本请先升级）
文件后缀必须是 .yaml、.yml 或 .json，且以 openapi: 开头
右下角状态栏应显示 YAML (OpenAPI) 或 OpenAPI Specification，不是 YAML 或 JSON
若点 Open Preview 却显示 No OpenAPI definition found，说明文档漏了 info 或 paths 这两个必需字段（openapi: 自己不算）