怎么用VSCode编写Swagger文档-OpenAPI预览与调试指南-VSCode-PHP中文网

VSCode原生支持OpenAPI 3.x预览，需满足三条件：文件为.yaml/.yml/.json、以openapi:开头、版本≥1.77；须手动设语言模式为OpenAPI Specification并配置v3.1 Schema映射，否则无法高亮或预览。

怎么用vscode编写swagger文档-openapi预览与调试指南

VSCode 本身不依赖任何“Swagger 插件”就能预览 OpenAPI 3.x 文档，但必须满足三个硬性条件：文件是 .yaml/.yml/.json、内容以 openapi: 开头、VSCode 版本 ≥ 1.77。装错插件或配错 Schema，反而会让预览失效、提示消失、$ref 报红。

怎么让 VSCode 正确识别 openapi.yaml 并启用预览

VSCode 不会自动把 openapi.yaml 当成 OpenAPI 文档——它默认只当普通 YAML。必须手动绑定语言模式和 Schema，否则连基础高亮都没有。

右键打开的 openapi.yaml 文件 → Change Language Mode → 选 OpenAPI Specification（不是 YAML 或 JSON）
点击右下角弹出的 Configure File Association for '.yaml' → 输入 openapi 确认
打开 settings.json，加这条 Schema 映射：
```
"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 等常用字段校验

为什么 $ref './components/schemas/User.yaml' 总报 file not found

$ref 在 VSCode 里不是“能读 YAML 就行”，它只认两种情况：引用目标是 JSON，或者目标 YAML 文件显式声明了 openapi: 版本号。没这行，Red Hat YAML 扩展直接跳过校验，导致路径解析失败。

所有被 $ref 引用的 YAML 文件（如 components/schemas/User.yaml）第一行必须是 openapi: 3.1.0 或 openapi: 3.0.3
路径只能用正斜杠 /，Windows 上写 .\components\schemas\User.yaml 必然失败
不能用 $ref: 'https://... —— VSCode 不发起网络请求校验远程地址，本地开发一律用相对路径
检查文件是否真实存在：隐藏后缀（如 User.yaml.txt）或大小写错误（user.yaml vs User.yaml）在 macOS/Linux 下也会触发 not found

点 Open Preview 却显示 “No OpenAPI definition found” 怎么办

这不是插件问题，是文档结构没通过最基础的 OpenAPI 合法性检查。VSCode 的内置校验比 YAML 解析器更严格，尤其卡在 enum 类型、content 嵌套、必需字段缺失上。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

确认根级有且仅有这三个字段：openapi、info、paths；缺任意一个，预览就为空
enum 值必须是字符串：enum: ["ACTIVE", "INACTIVE"] 合法，enum: [1, 2] 直接报错
content 下的 schema 不能扁平写：content: { application/json: { type: object } } 错；必须包一层：content: { application/json: { schema: { type: object } } }
用 https://www.php.cn/link/762d77fa312b52c109f63a9fa0b1edbe 先粘贴验证，比在 VSCode 里反复改保存更快

预览页面字体太小 / 右侧面板打不开 / 按钮不响应

预览界面由 VSCode 内置 Webview 渲染，不响应编辑器字体设置，也不支持 CSS 覆盖。很多“调 UI”的尝试其实是在改错地方。

放大预览字体唯一有效方式：系统级缩放（macOS：系统设置 → 显示器 → 缩放；Windows：设置 → 系统 → 显示 → 缩放）
禁用自动格式化防止 key 被重排：在 settings.json 加 "yaml.format.enable": false
如果右键没有 Open Preview to the Side，说明当前文件语言模式不是 OpenAPI Specification，右下角状态栏应显示该模式名，不是 YAML
禁用其他 YAML 相关插件（比如 Ansible、Docker Compose 语言支持），它们会劫持 *.yaml 关联，导致 OpenAPI 模式无法激活

最容易被忽略的是：VSCode 自带 OpenAPI 预览功能从不校验 $ref 是否真实指向有效结构，它只管语法和顶层字段。所以即使预览能打开、接口列表也出来了，$ref 指向一个空文件或格式错误的 YAML，也不会报错——直到你用 swagger-cli validate 或 CI 流程跑起来才暴露问题。