Swagger-Viewer插件仅支持swagger: "2.0"格式的.json/.yaml文件，不支持.openapi: 3.x、.yml后缀及$ref引用.yaml文件；VSCode 1.77+原生OpenAPI Editor更可靠，需满足openapi: 3.1.0开头、.yaml/.yml/.json后缀、语言模式设为OpenAPI Specification。
Swagger-Viewer 插件在 VSCode 里不能“实时渲染”本地接口文档——它只做静态预览，且对文件格式、路径、引用方式极其敏感；真正能点开就看的，是 VSCode 1.77+ 原生 OpenAPI Editor，不是这个插件。
为什么 Swagger-Viewer 点 Preview 没反应或报错
这不是插件坏了，是它根本没被触发：VSCode 不会自动把任意 .yaml 文件交给 Swagger-Viewer 处理。该插件只响应右键菜单显式调用，且只认两种情况：
- 文件后缀为
.json或.yaml（.yml不支持） - 内容以
swagger: "2.0"开头（openapi: 3.0.3或3.1.0会被忽略） - 右下角语言模式必须是
JSON或YAML，不能是OpenAPI Specification（否则原生预览抢跑，插件压根不加载）
常见错误现象：Command 'OpenAPI: Preview' not found —— 说明你装的是 Swagger-Viewer，但误用了 OpenAPI 相关命令名；它自己的命令是 Swagger: Preview。
如何让 Swagger-Viewer 正常工作（仅限 Swagger 2.0）
如果你的文档确实是 swagger: "2.0" 格式，且不想升级到 OpenAPI 3.x，按以下顺序操作：
- 卸载所有其他 OpenAPI/Swagger 插件（尤其是
OpenAPI Specification Editor和Swagger Viewer的变体），只留Swagger-Viewer（作者：Arjun Komath） - 确保文件名为
swagger.json或swagger.yaml（不能叫openapi.yaml） - 右键文件 →
Swagger: Preview（不是 “OpenAPI” 开头的命令） - 若仍空白，打开命令面板（
Ctrl+Shift+P），输入Swagger: Reload Preview手动刷新
注意：$ref 只支持同目录下的 .json 文件，./components/schemas/User.yaml 必然失败；Swagger 2.0 规范本身也不允许引用 .yaml。
更推荐的做法：直接用 VSCode 原生 OpenAPI Editor
VSCode 1.77+ 内置的预览能力比 Swagger-Viewer 更稳定、更严格、也更实用，尤其适合现代项目：
- 支持
openapi: 3.1.0，校验字段完整性（info、paths必须存在） - 配合
Red Hat YAML插件 + 手动绑定 Schema，能实现$ref跳转、enum字符串校验、字段补全 - 预览页支持折叠/展开路径、试调接口（需后端服务在线）、导出 HTML
- 不用记命令名，右上角固定有
Preview按钮（前提是语言模式设为OpenAPI Specification）
关键动作只有三步：改后缀为 .yaml → 第一行写 openapi: 3.1.0 → 右键 → Change Language Mode → 选 OpenAPI Specification。之后按钮自然出现。
复杂点永远在 $ref 和 enum 上
哪怕预览按钮出来了，$ref: ./schemas/User.yaml 报 file not found，大概率不是路径错了，而是被引用的 User.yaml 缺少 openapi: 3.1.0 开头；enum: [ACTIVE, INACTIVE] 报错，是因为没加引号——必须写成 enum: ["ACTIVE", "INACTIVE"]。这些细节 VSCode 原生校验会标红，但 Swagger-Viewer 完全不报，只会静默失败。
