Qoder 提供五种 OpenAPI 文档自动生成路径：Skill 快速生成、Quest Mode 全流程构建、CLI 批量处理、Rule 文件定制风格、Repo Wiki 同步变更日志，覆盖从单文件到全链路协同场景。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要为现有 API 项目生成规范、可执行的文档，但手动编写耗时易错、Swagger 注释遗漏或格式不统一，Qoder 提供五种自动生成路径，覆盖从单文件快速输出到全链路协同构建的完整场景。
用 Skill 快速生成 OpenAPI 3.0 文档
该方法无需修改代码，适合已有控制器但缺乏文档的存量项目，依赖预定义 Skill 自动提取路由与注解。
1、确保项目根目录下存在 controllers/ 或 src/main/java/com/example/controller/ 等典型 WebAPI 控制器路径
2、在 Qoder 编辑器中打开任意一个控制器文件（如 UserController.java 或 user.controller.ts）
3、在侧边聊天面板输入：为这个 API 生成文档
4、确认模型调用 api-doc-generator Skill 后，等待生成完成——这一步会自动解析 @PostMapping、@RequestBody、@ApiResponse 等关键元信息，若控制器未标注 HTTP 方法或参数类型，生成内容将缺失请求体结构，务必提前补全基础注解
5、生成结果包含 openapi.json 文件及配套 Markdown 文档，自动保存至项目 ./docs/api/ 目录
通过 Quest Mode 全流程构建 Swagger
适用于需同步更新代码与文档的协作场景，Agent 会主动校验注解完整性、补全缺失字段，并输出可直接部署的静态资源。
第一步：点击顶部导航栏 Quest 视图，新建任务并命名为 Generate Swagger Docs
第二步：在任务输入框中描述：基于当前项目生成完整 Swagger 文档，支持本地预览，并输出 YAML 和 HTML 两种格式
第三步：等待 Agent 自动识别技术栈（Spring Boot / .NET Core / Express.js 等），并加载对应解析规则——若项目使用了非标准路由注册方式（如动态注册 Bean），Agent 可能无法捕获全部端点，此时需在描述中追加说明：“请扫描所有 @Bean 注册的 RequestMappingHandlerMapping 实例”
第四步：Agent 将依次执行：扫描路由定义 → 提取 @Api、@ApiOperation 等注解 → 推断请求体与响应体结构 → 生成 openapi.yaml → 构建 Swagger UI 页面
第五步：在右侧面板 Preview Tab 中点击 Open in Browser 查看实时渲染效果
用 CLI 批量生成并注入配置
适合 CI/CD 流水线集成，通过命令行一次性处理多个模块，支持自定义输出路径与模板变量注入。
方法一：基础批量生成
执行 qoder-cli doc:generate --src ./src/controllers --output ./docs/swagger --format yaml
Qoder Linux版是由阿里推出的智能体自主开发工作台，支持开发者通过定义需求即可让Agent团队“自动驾驶”，自主完成代码执行、验证与交付的全流程。其全新的Quest独立视窗集成了任务管理与状态追踪能力，并支持跨项目多任务并行处理，显著提升开发效率。此外，Qoder还提供专家团模式与团队级知识引擎，适配复杂开发场景。
方法二：注入环境配置
在项目根目录创建 .qoder/config.yaml，写入 base-url: https://api.example.com/v1，再运行 qoder-cli doc:generate --inject-config .qoder/config.yaml
方法三：跳过特定包路径
添加 --exclude "test.*" 参数可忽略测试控制器，避免生成冗余接口条目
用 Rule 文件定制文档风格
当团队有强约束的文档规范（如必须包含“业务影响等级”字段、禁用某些 HTTP 状态码描述）时，Rule 文件可强制统一输出格式。
1、在项目 .qoder/rules/ 目录下新建 api-style.rule.yaml
2、写入字段级规则：response.status-codes: [200, 400, 401, 403, 404, 500]，表示只允许这六种状态码出现在文档中
3、启用规则：qoder-cli doc:generate --rule .qoder/rules/api-style.rule.yaml
注意：Rule 文件中定义的 required-fields 若在代码中缺失对应注解，CLI 将报错中断而非静默忽略，必须确保所有控制器类上存在 @Api(tags = ["用户"]) 类型声明
同步 Repo Wiki 更新变更日志
该方式将文档生成与代码演进绑定，每次 Git 提交后自动触发差异分析，仅更新变动接口的描述与示例。
1、在 Qoder IDE 中右键项目根目录 → 选择 Enable Repo Wiki Sync
2、首次运行时，Qoder 会扫描全部历史提交，建立接口签名快照库
3、后续每次 git push 后，系统自动比对新旧 commit 的 AST 差异，识别出新增/删除/参数变更的端点
4、变更日志以 Markdown 表格形式追加至 ./docs/CHANGELOG.md，包含“接口路径｜变更类型｜影响范围｜示例请求片段”五列
5、若某次提交仅修改了内部 Service 层逻辑而未触碰 Controller，Repo Wiki 不会生成任何日志条目——它只跟踪暴露给外部的契约层变动
