VSCode需手动设置语言模式为OpenAPI Specification并配置yaml.schemas绑定v3.1 Schema，引用文件须以openapi: 3.1.0开头、用正斜杠路径，文档必须含openapi/info/paths三要素，调试依赖后端挂载Swagger UI及进程附加。
VSCode 本身不运行 Swagger UI，也不直接调试接口——它只负责编辑、校验、预览 OpenAPI 文档，并通过启动后端服务（如 Express、FastAPI、.NET Core）来暴露可交互的 Swagger UI 页面；调试接口靠的是附加到 Node/Python/.NET 进程，而不是“在编辑器里点按钮就发请求”。
怎么让 openapi.yaml 文件真正被 VSCode 识别为 OpenAPI 文档
VSCode 不会自动把 openapi.yaml 当成 OpenAPI 文件，哪怕文件名和内容都对。必须手动绑定语言模式和 Schema，否则没有高亮、没提示、$ref 报红、预览按钮压根不出现。
- 右键打开的
openapi.yaml→ Change Language Mode → 选OpenAPI Specification（不是 YAML 或 JSON） - 右下角状态栏应显示
YAML (OpenAPI)；若显示YAML，说明没绑对 - 打开
settings.json，加这条（路径必须是 v3.1，不是 v3.0）："yaml.schemas": { "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": ["*.yaml", "*.yml"] } - 改完保存，重新打开文件；再看问题面板（
Cmd+Shift+M）有没有波浪线——有，说明校验已生效
为什么 $ref './components/schemas/User.yaml' 总报 file not found
$ref 在 VSCode 里不是“能读 YAML 就行”，它只认两种引用目标：JSON 文件，或 YAML 文件第一行明确写了 openapi: 3.1.0。没这行，Red Hat YAML 插件直接跳过解析，路径就失效。
- 所有被
$ref引用的 YAML 文件（比如components/schemas/User.yaml），第一行必须是openapi: 3.1.0或openapi: 3.0.3 - 路径只能用正斜杠
/，写成.\components\schemas\User.yaml必然失败（Windows 也一样） - 检查文件真实存在：隐藏后缀（
User.yaml.txt）、大小写错误（user.yamlvsUser.yaml）在 macOS/Linux 下也会触发 not found -
$ref不支持https://地址——VSCode 不发起网络请求，本地开发一律用相对路径
预览打不开 / 显示 “No OpenAPI definition found” 怎么办
这不是插件坏了，是文档结构没通过最基础的 OpenAPI 合法性检查。VSCode 的内置校验比大多数 YAML 解析器更严格，尤其卡在必需字段缺失、缩进错位、enum 类型写法不对这些地方。
- 确认文档开头是
openapi: 3.1.0（不是swagger:，也不是openapi: "3.1.0"带引号） - 必须包含
info和paths两个顶层字段，缺一不可 -
paths下至少有一个路径（如/users），且不能缩进错格——YAML 对空格极其敏感 - 如果用了
content字段嵌套schema，确保schema下有type或$ref，不能空着
调试接口 ≠ 在 VSCode 里点“执行”按钮
VSCode 没有内置 HTTP 客户端发请求的能力（除非装 REST Client 插件），所谓“调试接口”，实际是两件事：一是让后端服务跑起来并挂载 Swagger UI；二是用 VSCode 附加到该进程做断点调试。两者不能混为一谈。
- 确保后端已正确挂载 Swagger UI 路由，例如 Express 中：
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec)) - 启动服务后，在浏览器访问
http://localhost:3000/api-docs能打开 UI，才说明后端配置成功 - VSCode 的
launch.json需设"console": "integratedTerminal"，禁用"internalConsoleOptions": "neverOpen"，否则看不到端口冲突或启动失败日志 - 想真正在 VSCode 里调试接口逻辑，得在控制器代码里打断点，然后用
--inspect-brk启动 Node 进程，再用 VSCode 的 Attach 模式连接
最容易被忽略的点：文档写得再规范，如果后端没挂上 Swagger UI，VSCode 所有预览和配置都只是纸上谈兵；反过来，UI 能打开但文档校验总失败，大概率是 openapi: 版本声明、$ref 目标文件头、或 paths 缩进出了问题——这些细节不解决，预览永远是空白。
