VSCode本身不内置API文档编辑能力，但通过Red Hat YAML与OpenAPI Editor插件组合，可实现写、校验、预览全流程；需配置yaml.schemas匹配v3.1 schema并确保$ref文件以openapi: 3.1.0开头、用正斜杠路径。
VSCode 本身不内置 API 文档编辑能力，但用对插件组合，就能在编辑器里完成「写、校验、预览、测试、发布」全流程——Apifox 不是 VSCode 插件，它是个独立桌面应用，强行集成反而破坏工作流；真正高效的做法是用原生插件链替代「导入导出」式伪集成。
Red Hat YAML + OpenAPI (Swagger) Editor 是唯一靠谱的 YAML 编辑组合
装错插件是新手最常踩的坑。VSCode 扩展市场搜 “Swagger” 会出来十几款，但只有这两个能协同工作：
-
Red Hat YAML：提供 YAML 语法高亮、自动补全、$ref跳转，关键还能做 OpenAPI Schema 校验 -
OpenAPI (Swagger) Editor：侧边实时预览、接口折叠、错误高亮、参数树展开 - 禁用
Swagger Viewer：它和上面那个插件抢.yaml文件关联，一开就预览失败 - 别碰
Swagger Tools：已停更，$ref跨文件直接报file not found
装完不生效？大概率是没配 yaml.schemas。打开 VSCode 设置 → 搜 yaml.schemas → 编辑 settings.json，加这一行：
"yaml.schemas": {
"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": ["openapi.yaml"]
}注意路径必须是 v3.1/schema.json，不是 v3.0；匹配范围建议锁定为 openapi.yaml，避免误伤 docker-compose.yml 这类普通 YAML。
REST Client 插件才是真正的「文档即测试」落地工具
很多人以为 API 文档就是写 YAML，其实面向开发者的有效文档，是能直接点「Send Request」跑通的 .http 文件。这才是团队协作时最省心的形态：
- 请求自带环境变量（
{{baseUrl}}），状态栏一键切换 dev/staging/prod - 支持链式调用：
POST /login返回的 token 可直接用于下个GET /user的Authorization头 - 注释即分组：
### 用户管理、### 订单查询，生成的文档天然有结构 - 所有
.http文件可提交 Git，和代码一起版本控制，没人再问“这个接口怎么调”
示例片段：
### 登录
POST {{baseUrl}}/auth/login
Content-Type: application/json
<p>{
"email": "{{$processEnv EMAIL}}",
"password": "{{$processEnv PASSWORD}}"
}</p><h3>获取资料（自动复用上一步 token）</h3><p>GET {{baseUrl}}/user/profile
Authorization: Bearer {{login.response.body.access_token}}注意变量名 login 必须和上一个请求的 @name login 一致，否则取不到响应体。
$ref 报 file not found？90% 是路径或格式没对
拆分 OpenAPI 文件时，$ref: './schemas/user.yaml' 看起来没问题，但 VSCode 默认不认 YAML 文件为可引用目标。必须同时满足这四点：
- 被引用的
user.yaml文件开头必须有openapi: 3.0.3或openapi: 3.1.0，否则Red Hat YAML不识别为 OpenAPI 文档 - 路径必须用正斜杠
/，不能用 Windows 风格的反斜杠\ - 文件名不能带隐藏后缀（比如其实是
user.yaml.txt） - 不支持
$ref: 'https://...远程地址，本地开发一律用相对路径
如果引用层级深（比如 ./v1/schemas/user.yaml），建议在 settings.json 里把匹配范围从 ["openapi.yaml"] 改成 ["**/openapi.yaml", "**/schemas/*.yaml"]，显式声明哪些子目录下的 YAML 也要走 OpenAPI 校验。
复杂点在于 Schema 关联和 $ref 解析是两套机制，前者靠 yaml.schemas 配置，后者靠文件头声明+路径规范。漏掉任一环，VSCode 就当普通 YAML 处理，不校验、不跳转、不预览——这不是插件问题，是配置没对齐。
