VSCode点“Preview Swagger”打不开UI，首要确认文件是否为真OpenAPI：必须以openapi: 3.1.0开头，且含info和paths字段（即使为空对象{}），后缀为.yaml/.yml/.json；右下角状态栏须显示OpenAPI Specification而非YAML。
VSCode 里点“Preview Swagger”打不开 UI？先确认文件是不是真 OpenAPI
VSCode 内置预览或 Swagger Viewer 插件报 “No OpenAPI definition found”，90% 不是插件坏了，而是文档没通过最基础校验。它不看内容多漂亮，只认三件事：openapi: 开头、info 和 paths 字段必须存在（哪怕空对象 {}）、文件后缀是 .yaml / .yml / .json。
常见卡点：
- 文件第一行写的是
swagger: "2.0"或openapi: 3.0.0—— VSCode ≥1.77 只认openapi: 3.1.0才启用完整校验和预览 -
info:下面漏了title或version，或者整个info块被删了 - 右下角状态栏显示的是
YAML而不是OpenAPI Specification，说明语言模式没绑定成功
装了 Swagger Viewer 却跳转失败、$ref 报 file not found？路径和格式全得对
Red Hat YAML 插件做 $ref 解析时非常严格：它不读文件内容，只按规则匹配“是否 OpenAPI 文档”。一旦失败，就直接跳过校验，连报错都懒得给。
必须同时满足：
- 被引用的文件（比如
./components/schemas/User.yaml）第一行必须是openapi: 3.1.0 - 路径只能用正斜杠
/，Windows 上写.\components\schemas\User.yaml必然失败 - 不能用
$ref: 'https://...—— VSCode 不发起网络请求，本地开发一律禁用远程引用 - 检查真实文件名：macOS/Linux 区分大小写，
User.yaml和user.yaml是两个文件；Windows 上可能隐藏了.txt后缀
想在 VSCode 里试请求（Try it out）？别指望预览面板，得换路子
VSCode 内置预览、OpenAPI (Swagger) Editor 插件、甚至 Swagger Viewer 的预览面板，全部是只读渲染——它们不发 HTTP 请求，也不连你本地服务。所谓“试请求”，本质是前端调用浏览器 fetch，目标地址得能被浏览器直连。
真正能跑通的组合只有两个：
- 用
REST Client插件：把接口定义复制成.http文件，手动填GET http://localhost:3000/api/users，Ctrl+Alt+R 直接发 - 启动真实后端服务（如 Express +
swagger-ui-express），确保app.use('/api-docs', ...)挂载成功，然后浏览器访问http://localhost:3000/api-docs—— 这才是 Swagger UI 的正确打开方式
注意：launch.json 中若设了 "internalConsoleOptions": "neverOpen"，终端日志会被吞掉，服务启没启动、端口占没占住，你根本看不到。
多人协作改 openapi.yaml，怎么避免一合并就红？靠配置不是靠自觉
团队里一个人加了个 $ref，另一个人删了对应文件，Git 合并完预览直接挂——这不是运气差，是没设防。
必须落地的三项约束：
- 项目根目录加
.editorconfig，强制indent_style = space、indent_size = 2，杜绝空格 Tab 混用导致 YAML 解析失败 - VSCode
settings.json里关掉自动重排："yaml.format.enable": false，否则每次保存字段顺序乱跳，Git diff 失效 - 加 pre-commit 钩子：
swagger-cli validate openapi.yaml，提交前硬卡住非法结构（比如缺info、paths，或enum值重复）
最易忽略的一点：所有 $ref 目标文件，哪怕只是空壳，也必须以 openapi: 3.1.0 开头，否则 Red Hat YAML 插件根本不把它当 OpenAPI 文档处理，后续一切校验、跳转、补全都失效。
