vscode 自带 openapi editor 原生支持 v3.x 文件预览，无需安装 swagger 插件；需满足版本 ≥1.77、文件为 .yaml/.yml/.json 且以 openapi: 开头，校验严格需注意 $ref 路径、enum 字符串化及 schema 嵌套格式。

VSCode 里直接预览 OpenAPI 文件，不用装 Swagger 插件

OpenAPI（v3.x）文件在 VSCode 里默认就能预览，根本不需要额外装 Swagger Viewer 或 OpenAPI Preview 这类插件——它们要么已停更，要么只支持 v2（Swagger），打开 v3 文件会报错或空白。

VSCode 自带的 OpenAPI Editor 功能（由 Red Hat 提供，已内置在较新版本中）原生支持 openapi: 3.0.0 及以上，点击右上角 Preview 按钮即可渲染交互式文档。

• 确认 VSCode 版本 ≥ 1.77（低于此版本可能无该功能，升级最省事）
• 文件后缀必须是 .yaml、.yml 或 .json，且内容以 openapi: 开头（不是 swagger:）
• 如果没看到预览按钮，右键文件 → Open With → 选 OpenAPI Editor（首次可能需手动设置默认编辑器）

点开预览却显示 “Invalid OpenAPI document” 怎么办

这是最常见的卡点：语法合法 ≠ OpenAPI 合法。VSCode 的校验比 YAML 解析器更严格，尤其对引用、枚举、schema 结构敏感。

VSCode

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

下载

• $ref 必须指向本地相对路径（如 ./components/schemas/User.yaml），不支持 URL 或绝对路径
• 所有 enum 值必须是字符串类型，写 enum: [1, 2] 会失败，得写成 enum: ["1", "2"]
• content 下的 schema 不能直接写 type: object，必须包一层 schema:，比如：

  content:
    application/json:
      schema:
        type: object

• 用 yq 或在线工具 https://editor.swagger.io 先验证结构，比在 VSCode 里反复试更快

想改字体大小或禁用自动格式化？改 settings.json 就行

VSCode 的 OpenAPI 预览界面本身不提供 UI 设置项，但底层依赖 YAML 扩展行为，调整相关配置即可影响预览体验。

• 禁用保存时自动排序 key：在 settings.json 加 "yaml.format.enable": false
• 放大预览字体：加 "workbench.fontAliasing": "antialiased" + 调整系统缩放（预览页不响应 editor.fontSize）
• 避免 .yaml 文件被其他插件劫持：检查 files.associations 是否把 *.yaml 错配给了 ansible 或 dockercompose 语言模式

需要生成 mock server 或导出 HTML？别在 VSCode 里硬扛

VSCode 的预览只是只读查看，不提供 mock、测试、导出等功能。强行找插件补这些能力，大概率遇到兼容问题或权限警告。

• 本地起 mock：用 openapi-backend（Node）或 prism（Docker），命令一行启动：

  npx @stoplight/prism-cli mock api.yaml

• 导出静态 HTML：用 redoc-cli，比插件生成的质量稳定：

  npx redoc-cli bundle api.yaml

• CI/CD 中验证：用 speccy 或 openapi-validator 做 lint，而不是依赖 VSCode 界面提示

VSCode 预览的核心价值是快速确认结构是否可读、路径和参数有没有明显拼写错误——更重的活，交给专用工具有时反而更快。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！