VSCode for API Documentation：使用Swagger/OpenAPI_网络技术

在 VSCode 中可通过安装 Red Hat YAML 和 Swagger Viewer 扩展、配置 OpenAPI Schema 绑定、使用 Swagger: Preview 命令预览、运行 swagger-cli validate 验证及启用 Ctrl+Click 跳转与自动补全，实现 OpenAPI 文档的高效编写与交互式预览。

如果您希望在 Visual Studio Code 中高效编写和预览 API 文档，Swagger 或 OpenAPI 规范是主流选择。VSCode 本身不原生支持 OpenAPI 渲染，但可通过扩展与配置实现语法高亮、自动补全、实时预览及验证功能。以下是具体实施步骤：

本文运行环境：MacBook Pro，macOS Sequoia。

一、安装 OpenAPI 相关扩展

VSCode 需借助社区扩展识别 OpenAPI 文件格式（如 .yaml 或 .yml），提供结构化编辑支持。核心扩展可同时满足语法校验、缩进提示与文档跳转能力。

1、打开 VSCode，点击左侧活动栏的扩展图标（或按 Cmd+Shift+X）。

2、在搜索框中输入 Red Hat YAML，找到官方发布的 YAML Language Support by Red Hat 扩展并安装。

3、再次搜索 Swagger Viewer，安装由 Arjun Komath 提供的同名扩展，用于内联预览 OpenAPI 文档。

4、重启 VSCode 使扩展生效。

二、配置 YAML 扩展以识别 OpenAPI 文件

Red Hat YAML 扩展默认不将 .yaml 文件自动关联为 OpenAPI 模式，需手动指定文件关联与 Schema 绑定，从而启用语义验证与智能提示。

1、按下 Cmd+, 打开设置界面，点击右上角“打开设置（JSON）”图标。

2、在 settings.json 中添加以下配置项：

3、在 yaml.schemas 对象内插入键值对："https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json" 作为值，"*.yaml" 和 "*.yml" 作为键（可合并为数组）。

4、保存文件后，新建或打开任意 .yaml 文件，右下角状态栏应显示 YAML (OpenAPI) 模式。