VSCode 1.77+ 原生支持 OpenAPI v3.x 预览，但需文件后缀为.yaml/.yml/.json且首行为openapi:，再手动设语言模式为OpenAPI Specification；自动补全等高级功能须配置Red Hat YAML插件绑定OpenAPI Schema。
VSCode 1.77+ 原生支持 OpenAPI v3.x 预览，不用装 Swagger 插件；但想获得自动补全、错误高亮和跨文件跳转，必须装 Red Hat YAML + OpenAPI (Swagger) Editor 组合。
为什么预览按钮不出现或点开是空白
不是插件没装对，而是 VSCode 没把当前文件识别为 OpenAPI 模式。它只认三种后缀：.yaml、.yml、.json，且内容第一行必须是 openapi:（不能是 swagger:）。
- 右键文件 → Change Language Mode → 选
OpenAPI Specification（不是 YAML 或 JSON） - 接着点击右下角弹出的 Configure File Association for '.yaml'，输入
openapi回车，这样所有.yaml文件默认就走 OpenAPI 模式了 - 如果仍不显示预览按钮，按
Ctrl+Shift+P输入命令OpenAPI: Open Preview to the Side手动唤出
自动补全失效或 enum 报错：Red Hat YAML 的 Schema 绑定必须手动配
Red Hat YAML 插件本身不自动关联 OpenAPI Schema，不配置就只有基础 YAML 补全，没有字段提示、必填校验、$ref 跳转这些能力。
- 打开
settings.json，加这段：
{
"yaml.schemas": {
"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": [
"*.yaml",
"*.yml",
"*.json"
]
}
}
-
enum字段必须写字符串数组，enum: ["200", "404"]合法，enum: [200, 404]直接触发Invalid OpenAPI document -
$ref只支持相对路径，./components/schemas/User.yaml可以，https://example.com/schema.json或/abs/path.yaml全部报错
Preview 显示 “Invalid OpenAPI document” 的真实原因
这不是语法错误，是 OpenAPI 结构校验失败。VSCode 内置校验器比 YAML 解析器严格得多，尤其卡在 schema 嵌套层级和 content 定义上。
-
content下必须显式包一层schema:，下面这样会失败：
content:
application/json:
type: object
- 正确写法是：
content:
application/json:
schema:
type: object
- 根级字段缺失也会触发，确保至少有
openapi、info、paths三个顶层 key - 调试建议：先用在线工具 https://www.php.cn/link/762d77fa312b52c109f63a9fa0b1edbe 验证结构，再回 VSCode，避免反复试错
字体太小、格式被乱改、预览页卡顿怎么办
OpenAPI 预览界面本身没 UI 设置项，所有调整都得靠底层配置干预。
- 禁用保存时自动重排 key：
"yaml.format.enable": false - 放大预览字体：预览页不响应
editor.fontSize，得靠系统缩放 +"workbench.fontAliasing": "antialiased" - 避免
.yaml被其他插件劫持：检查files.associations，删掉类似"*.yaml": "ansible"这种误配 - 如果预览卡顿，关掉
OpenAPI (Swagger) Editor插件里「Enable auto-refresh on file change」选项，大文件编辑时很关键
最易忽略的一点：VSCode 的预览只是只读查看，不提供 mock server、导出 HTML、生成 client code 等功能——这些必须交给专门工具链，比如 openapi-generator 或 prismmock，别在编辑器里硬扛。
