VSCode 1.77+ 原生支持 OpenAPI v3.x 预览，无需插件即可点击 Preview 按钮；但自动补全、$ref 跳转、enum 校验和错误高亮需手动配置 Red Hat YAML 插件及 v3.1 Schema 绑定，并确保文件后缀为 .yaml/.yml/.json、首行为 openapi:、语言模式设为 OpenAPI Specification。
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 跳转这些能力。
- 打开
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.yamlvsUser.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:自己不算）
最易被忽略的是：每个被 $ref 引用的子文件都得有 openapi: 行，哪怕只是空文档；还有 yaml.schemas 配置里用了 v3.0 而不是 v3.1，会导致 nullable、example 等字段不被识别，校验就断了。
