VSCode本身不生成接口文档，它只预览、扫描或调用外部工具；真正产出文档的是运行时库（如springdoc-openapi）或CLI工具（如openapi-generator），插件仅作为桥梁。
VSCode 本身不生成接口文档，它只预览、扫描或调用外部工具——真正产出文档的，是运行时库（如 springdoc-openapi）或 CLI 工具（如 openapi-generator），VSCode 插件只是桥梁。
为什么“右键 Generate OpenAPI”经常没反应
多数插件的 Generate OpenAPI 命令依赖两个前提：文件必须是合法的 OpenAPI/YAML 格式（开头含 openapi: 3.0.3 或 swagger: "2.0"），且光标需落在该文件内。常见失效原因包括：
- 误在
.ts或.java文件里触发命令——插件不会解析代码逻辑，只扫描注释块（如@Operation）或读取已导出的 JSON - 装了名字带 “Swagger” 但只做语法高亮的插件（例如 Swagger Viewer 不提供生成能力）
- YAML 文件里用了
$ref指向本地./schemas/user.yaml，而插件默认不合并外部引用
从代码注释生成文档的实际路径
想让 VSCode “参与”生成过程，得先让后端暴露标准接口描述。以 Spring Boot + OpenAPI 3 为例：
- 在项目中引入
springdoc-openapi-ui依赖，启动后自动提供/v3/api-docsJSON 接口 - 安装插件
Swagger Viewer，按Ctrl+Shift+P输入OpenAPI: Fetch and Preview，填入http://localhost:8080/v3/api-docs - 插件会拉取 JSON 并渲染成交互式文档——这不是“生成”，而是“抓取+预览”
- 若要用该 JSON 生成 SDK，需配合
openapi-generator-cli手动执行：openapi-generator generate -i http://localhost:8080/v3/api-docs -g typescript-axios -o ./client
更轻量的替代方案：用 REST Client 直接沉淀文档
如果你没有后端运行时支持，又想快速产出可读接口说明，REST Client 插件能变相充当文档载体：
- 新建
api.http，写请求并加注释：### GET User by ID（###是分隔符，会被识别为章节标题） - 支持环境变量（
rest-client.environment.json），不同环境的 URL、Token 可统一管理 - 响应体里的 JSON 示例可复制进
JSON to TS插件，一键生成interface User - 整个
.http文件可提交 Git，团队成员直接点击Send Request就能验证，比静态 Markdown 更可靠
真正的难点不在插件怎么点，而在文档契约是否由代码定义、是否被运行时暴露、是否与实现保持同步——VSCode 永远只负责“看见”和“传递”，不负责“决定”。
