应安装red hat yaml和openapi (swagger) editor插件组合，前者提供yaml语法与json schema校验，后者支持侧边预览、错误高亮与接口折叠；禁用swagger viewer等无效插件。
Swagger插件装哪个？别选错名字
VSCode里搜“Swagger”会出来一堆名字带 Swagger 的插件，但真正能校验 OpenAPI 3.x（也就是现在主流的 openapi: 3.0.3 或 3.1.0）并支持实时语法提示的，只有 Red Hat YAML + OpenAPI (Swagger) Editor 这个组合。Swagger Viewer 只能看，不校验；Swagger Tools 已停更，遇到 $ref 跨文件就报错；OpenAPI Generator 是生成代码用的，不是写文档的。
- 必装：
Red Hat YAML（提供 YAML 语法支持 + JSON Schema 校验能力） - 必装：
OpenAPI (Swagger) Editor（提供侧边预览、错误高亮、接口折叠） - 禁用：
Swagger Viewer（和上面那个插件冲突，会抢.yaml文件关联）
YAML 文件怎么自动绑定 OpenAPI Schema？
装完插件，打开 api.yaml 还是没提示、没报错？问题大概率出在 Schema 关联没生效。VSCode 不会自动识别你写的 openapi: 3.0.3 就去拉官方 Schema，得手动告诉它。
- 在 VSCode 设置里搜
yaml.schemas，点「编辑 in settings.json」 - 加一条映射：
"yaml.schemas": { "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": ["*.yaml", "*.yml"] } - 注意：路径必须是
v3.1/schema.json，别用 v3.0 的——后者不支持nullable、example在 schema 内直接写等常见写法 - 如果只校验部分文件（比如只校验
openapi.yaml），把["*.yaml"]换成["openapi.yaml"]，避免误伤其他配置文件
引用外部定义（$ref）为啥总报 “file not found”？
这是最常卡住人的地方。OpenAPI 支持用 $ref: './schemas/user.yaml' 拆分文件，但 VSCode 默认不解析相对路径里的 .yaml 文件——它只认 .json，除非你显式声明。
- 所有被
$ref引用的 YAML 文件，必须以openapi: 3.0.3（或 3.1.0）开头，否则Red Hat YAML不认为它是 OpenAPI 文档 - 路径不能用 Windows 风格反斜杠
\，必须用正斜杠/，哪怕你在 Windows 上 - 如果引用的是同目录下
schemas/user.yaml，确保该文件真实存在，且没有隐藏后缀（比如其实是user.yaml.txt） - 不支持
$ref: 'https://...远程地址校验（会超时或被 CORS 拦），本地开发请一律用相对路径
预览页面打不开 / 接口列表为空？检查这三点
点击右上角 Open Preview 按钮，弹出空白页或只显示 “No OpenAPI definition found”，通常不是插件坏了，而是定义本身没通过基础校验。
- 文件编码必须是 UTF-8，不能是 GBK 或 UTF-8-BOM（BOM 会导致
openapi:前多出不可见字符，解析失败） - 第一行必须是
openapi: 3.0.3，不能缩进，不能前面空行，不能写成openapi: "3.0.3"（加引号会当字符串处理，不触发 Schema 绑定） -
paths:下至少有一个路径，比如/users:，如果整个paths块被注释掉或漏写，预览页就什么也不显示
改完记得保存文件，VSCode 不会热重载 Schema 绑定逻辑。
有些团队用 components/schemas 写得特别全，但忘了补 paths，结果文档写了一半，预览却像没写一样——这点最容易被忽略。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
