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。

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"]
  }

• 如果只想校验 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 就当它不存在，连错误提示都懒得给。盯着预览空白页发呆前，先看问题面板里的红色波浪线，那才是真实线索。