VSCode 1.77+已原生支持OpenAPI 3.x预览，无需额外插件；需满足：文件为.yaml/.yml/.json后缀、以openapi: 3.0.3或3.1.0开头、语言模式设为OpenAPI Specification，并在settings.json中配置v3.1 Schema校验。
VSCode 本身已内置 OpenAPI 预览能力，不需要装 Swagger Viewer 或 OpenAPI Preview 这类过时/不兼容的插件——它们要么只支持 Swagger 2.0，要么在打开 openapi: 3.1.0 文件时直接报错或空白。
确认 VSCode 版本和文件基础条件
预览功能从 VSCode 1.77 起原生支持，低于此版本请先升级。不升级就卡在“没按钮”“点不开”上，纯属白调。
- 文件后缀必须是
.yaml、.yml或.json（.swagger不行） - 内容开头必须是
openapi: 3.0.3或openapi: 3.1.0（写swagger:就不认） - 右下角状态栏应显示 “YAML (OpenAPI)” 或 “OpenAPI Specification”，不是 “YAML” 或 “JSON”
- 如果没显示，右键文件 → Change Language Mode → 选
OpenAPI Specification
手动绑定 OpenAPI Schema 才有语法校验和提示
装了 Red Hat YAML 插件也不代表自动校验——VSCode 不会自己去扒 GitHub 上的官方 Schema。必须显式告诉它哪个文件该用哪个 Schema。
- 打开
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"] } - 如果只想校验
openapi.yaml，把["*.yaml", "*.yml"]换成["openapi.yaml"] - 改完保存，重新打开文件，再看问题面板（
Cmd+Shift+M）有没有红色波浪线
$ref 引用外部 YAML 文件总报 file not found？
这是最常打断编辑流的问题：你写了 $ref: './schemas/user.yaml'，VSCode 却说找不到——不是路径错了，是它默认不解析 YAML 后缀的引用文件。
- 被引用的
user.yaml文件必须以openapi: 3.0.3或openapi: 3.1.0开头（哪怕只是空文档，也得有这行） - 路径必须用正斜杠
/，不能用 Windows 风格的反斜杠\ - 确保文件真实存在，且没有隐藏后缀（比如实际是
user.yaml.txt） -
$ref不支持https://远程地址（本地开发别试，必超时或 CORS 拦）
预览打不开 / 显示 No OpenAPI definition found
不是插件坏了，是文档本身没通过最基础的 OpenAPI 结构校验。VSCode 的预览器比人还严格。
- 检查是否漏了
info和paths这两个必需字段（openapi:自己不算） - YAML 缩进错一格，整个
paths就可能被忽略，预览里就只剩空白 - 所有
enum值必须是字符串（enum: [admin, user]错，得写enum: ["admin", "user"]） - 如果用了
nullable: true，Schema 必须是 v3.1（v3.0 不支持，会静默失败）
真正麻烦的从来不是装插件，而是 OpenAPI 规范本身对结构、缩进、类型、引用路径的隐性要求——这些细节不满足，VSCode 就当它不存在，连错误提示都懒得给。盯着预览空白页发呆前，先看问题面板里的红色波浪线，那才是真实线索。
