Qoder 提供了五种 API 文档自动生成方案，覆盖从快速原型搭建到 CI/CD 集成的完整链路。如果你正在为现有项目折腾 Swagger 文档，既担心手动维护跟不上节奏，又害怕遗漏注释导致格式混乱，那么下面这几种实战技巧可以直接拿来用。
一、使用 Qoder Skill 快速触发 API 文档生成
这一招最为轻量，适合那些想快速验证接口文档、同时又不想改动代码的场景。Qoder 的 Skill 功能就像一个智能扫描仪：你只需在编辑器中打开一个控制器文件（比如 UserController.java 或 user.controller.ts），然后在聊天面板输入一句“为这个 API 生成文档”，它就会自动解析路由、注解、参数类型以及响应模型，最终输出一份符合 OpenAPI 3.0 标准的文档。
具体操作非常简单：
- 确保项目根目录下有典型的控制器路径（比如
controllers/或src/main/java/com/example/controller/） - 在 Qoder 编辑器中打开其中一个控制器文件
- 在侧边聊天面板输入指令
- 确认调用了
api-doc-generator这个 Skill 后，等待生成 - 结果会自动保存到项目
./docs/api/目录下，包含openapi.json和配套的 Markdown 文档
二、通过 Quest Mode 全流程驱动 Swagger 文档构建
如果你的需求更为复杂——不仅需要生成文档，还要同步代码变更、校验注解完整性，并最终部署一套可预览的 Swagger UI——那就得使用 Quest Mode。在此模式下，Qoder 会启动一个多步骤的 Agent 流程，自动识别你使用的是 Spring Boot、.NET Core 还是 Express.js，然后加载对应的解析规则。
操作流程如下：点击顶部导航栏的 Quest 视图，新建任务并命名为“Generate Swagger Docs”。在任务输入框里清晰描述需求（例如“基于当前项目生成完整 Swagger 文档，支持本地预览，并输出 YAML 和 HTML 两种格式”）。Agent 会自动依次执行：扫描路由定义 → 提取 @Api、@ApiOperation 等注解 → 推断请求体与响应体结构 → 生成 openapi.yaml → 构建 Swagger UI 页面。最后在右侧面板的 Preview Tab 里点击“Open in Browser”即可看到实时渲染效果。
三、利用 Qoder CLI 批量生成并注入 Swagger 配置
面向 DevOps 场景，CLI 方式才是王道。一条命令下去，文档生成和配置注入一气呵成，还能无缝嵌入 CI/CD 流水线。在终端里进入项目根目录，执行 qoder-cli api:doc --output ./docs/swagger.json --format json。如果是 .NET Core 项目，CLI 会自动检测 Program.cs 并询问是否注入 Swashbuckle 服务注册代码。选择 Yes 后，它会自动添加 builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen();。接着执行 qoder-cli api:serve 启动内置 Swagger UI 服务（默认监听 http://localhost:5001/swagger），验证所有端点的 Summary、Parameters、Responses 字段都正确无误。
四、基于 Rule 文件定制 Swagger 文档风格与字段映射
团队协作时最大的痛点就是文档风格不统一。有人用中文，有人用英文，状态码说明五花八门。Qoder 的 Rule 机制正是为此而生。在项目根目录创建 .qoder/rules/swagger-rule.md 文件，开头用 YAML 元数据声明规则名称和描述，然后在正文里定义具体的替换规则。例如：将所有 id 参数的描述统一为 "Unique identifier of the resource"，将 HttpStatus.OK 映射为 "200 OK: Operation succeeded"，强制使用 "application/json" 作为默认媒体类型。保存后，在聊天窗口输入“应用 Swagger 自定义规则生成文档”，Qoder 就会加载 Rule 重新解析控制器——输出的文档中所有 id 参数描述都按规则替换，响应状态码也完全一致。
五、结合 Repo Wiki 自动同步 API 文档变更
最后这套方案解决的是文档永远滞后于代码的顽疾。Qoder 利用长期记忆机制持续追踪 API 变更历史。首次启用前，在项目设置中开启 Repo Wiki Sync for APIs 功能。之后一旦提交了含新增接口的代码（比如新增 POST /v1/orders），Qoder 会自动触发后台任务：识别新增端点、提取 JSDoc 或 XML 注释、生成变更摘要。在 Wiki 页面 /wiki/API-Change-Log 中就能看到类似 “[ADDED] POST /v1/orders — 创建新订单，支持库存预占与优惠券校验（2026-05-22）” 这样的条目。点击条目右侧的 View Diff 还能看到该接口在 Swagger JSON 中字段级别的原始变更对比，排查问题一目了然。
五种方法各有用武之地：手头项目临时查看接口，用 Skill；需要全流程文档治理，上 Quest；DevOps 流水线里想自动注入配置，CLI 最省心；团队风格统一靠 Rule 文件；长期维护文档同步，别忘了开启 Repo Wiki。选哪个，就看你的项目阶段和团队规范了。
```