安装OpenAPI Editor、Swagger Viewer等扩展后，在VS Code中编写YAML格式的OpenAPI文件，可实现实时语法检查、自动补全与内联预览，通过Prettier格式化并验证结构正确性，提升文档准确性与协作效率。
用 VS Code 写 API 文档，尤其是基于 Swagger（即 OpenAPI）规范时，效率和准确性都能大幅提升。VS Code 提供了丰富的插件支持、语法高亮、自动补全和实时预览功能，让编写 OpenAPI 文档变得更直观、更少出错。
安装必要的扩展
要高效编写 OpenAPI 文档，先在 VS Code 中安装几个关键扩展：
- OpenAPI (Swagger) Editor：由42Crunch提供，支持 YAML 和 JSON 格式的 OpenAPI 文件，具备语法检查、自动补全和错误提示。
- Swagger Viewer：可以内联预览 Swagger UI 界面，无需启动服务器就能查看文档效果。
- YAML：微软官方扩展，增强 YAML 文件的编辑体验，包括格式化和验证。
- Prettier：统一代码风格，可配置用于自动格式化 OpenAPI 文件。
创建并编辑 OpenAPI 文件
新建一个 openapi.yml 或 swagger.json 文件。推荐使用 YAML，结构更清晰易读。
输入基本框架：
openapi: 3.0.3
info:
title: 示例 API
version: 1.0.0
description: 一个简单的用户管理 API
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: 获取用户列表
responses:
'200':
description: 成功返回用户数组
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
编辑过程中，扩展会实时提示字段拼写错误、结构问题或缺失必填项。
实时预览 API 文档
安装 Swagger Viewer 后，右键点击 OpenAPI 文件，选择 “Preview” 即可在侧边栏打开交互式文档页面。
这个预览界面类似 Swagger UI，能展示接口路径、请求参数、响应示例，并支持尝试发送请求（如果配置了 CORS 或本地代理）。
你不需要运行后端服务，就能确认文档是否清晰、结构是否合理。
验证与格式化
确保文档符合 OpenAPI 规范很重要。上述扩展会在你编辑时标出错误，比如：
- 路径参数未在 parameters 中定义
- 引用的 schema 不存在
- 缺少 required 字段
配合 Prettier 设置保存时自动格式化，保持文档整洁一致。可以在项目根目录添加 .prettierrc 配置文件，启用对 YAML 的支持。
基本上就这些。VS Code 搭配合适的扩展，能把 OpenAPI 文档编写变成一种流畅、可靠的开发环节，尤其适合前后端协作或设计优先的 API 开发流程。不复杂但容易忽略的是及时验证和预览，这能避免后期集成出问题。
