qoder 提供五种 api 文档自动生成方法：一、用 skill 快速生成 openapi 3.0 文档；二、通过 quest mode 全流程构建 swagger；三、cli 批量生成并注入配置；四、rule 文件定制文档风格；五、同步 repo wiki 更新变更日志。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试为现有 API 项目生成规范、可执行的文档，但手动编写耗时易错、Swagger 注释遗漏或格式不统一，则可能是由于缺乏自动化文档生成机制。以下是使用 Qoder 实现 API 文档自动生成的多种实战方法：
一、使用 Qoder Skill 快速触发 API 文档生成
该方法基于预定义 Skill 指令，无需修改代码即可从项目结构中提取路由与注解，生成符合 OpenAPI 3.0 标准的 Swagger 文档。Qoder 通过解析控制器文件、HTTP 方法声明、参数类型及响应模型，自动构建接口描述。
1、确保项目根目录下存在 controllers/ 或 src/main/java/com/example/controller/ 等典型 WebAPI 控制器路径
2、在 Qoder 编辑器中打开任意一个控制器文件（如 UserController.java 或 user.controller.ts）
3、在侧边聊天面板输入：为这个 API 生成文档
4、确认模型调用 api-doc-generator Skill 后，等待生成完成
5、生成结果将包含 openapi.json 文件及配套 Markdown 文档，自动保存至项目 ./docs/api/ 目录
二、通过 Quest Mode 全流程驱动 Swagger 文档构建
该方法适用于需同步更新代码与文档的场景，Qoder 在 Quest 视图中启动多步骤 Agent 流程，自动扫描变更、校验注解完整性、补全缺失字段并导出可部署的 Swagger UI 静态资源。
1、点击顶部导航栏 Quest 视图，新建任务并命名为 Generate Swagger Docs
2、在任务输入框中描述：基于当前项目生成完整 Swagger 文档，支持本地预览，并输出 YAML 和 HTML 两种格式
3、等待 Agent 自动识别技术栈（Spring Boot / .NET Core / Express.js 等），并加载对应解析规则
4、Agent 将依次执行：扫描路由定义 → 提取 @Api、@ApiOperation 等注解 → 推断请求体与响应体结构 → 生成 openapi.yaml → 构建 Swagger UI 页面
5、在右侧面板 Preview Tab 中点击 Open in Browser 查看实时渲染效果
三、利用 Qoder CLI 批量生成并注入 Swagger 配置
该方法面向 DevOps 场景，通过命令行触发文档生成，并将生成结果自动写入项目配置文件（如 SpringDoc 配置类或 Swashbuckle Setup），实现 CI/CD 流水线集成。
1、在终端中进入项目根目录，执行：qoder-cli api:doc --output ./docs/swagger.json --format json
2、若项目为 .NET Core，CLI 将自动检测 Program.cs 并提示是否注入 Swashbuckle 服务注册代码
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、选择 Yes 后，CLI 修改 Program.cs，添加 builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen();
4、执行 qoder-cli api:serve 启动内置 Swagger UI 服务，默认监听 http://localhost:5001/swagger
5、验证页面中所有端点均显示正确 Summary、Parameters、Responses 字段，无 undefined 占位符
四、基于 Rule 文件定制 Swagger 文档风格与字段映射
该方法用于统一团队文档规范，通过编写 .qoder/rules/swagger-rule.md 文件，强制约束生成内容中的标题命名、状态码说明、示例数据格式等细节，避免人工干预偏差。
1、在项目根目录创建 .qoder/rules/ 文件夹，并新建 swagger-rule.md
2、在文件开头添加 YAML 元数据：--- name: swagger-custom-rules description: Enforce team-specific Swagger doc style and field mapping ---
3、在正文部分定义规则：- Replace all 'id' parameter descriptions with 'Unique identifier of the resource' - Map HttpStatus.OK to '200 OK: Operation succeeded' in Responses section - Use 'application/json' as default request/response media type
4、保存后，在 Qoder 聊天窗口输入：应用 Swagger 自定义规则生成文档
5、Qoder 加载 Rule 后重新解析控制器，输出文档中所有 id 参数描述已按规则替换，且响应状态码说明完全一致
五、结合 Repo Wiki 自动同步 API 文档变更
该方法解决文档滞后问题，Qoder 利用长期记忆机制持续追踪 API 变更历史，当控制器被修改时，自动比对前后差异并更新 Wiki 页面中的接口列表、参数变更日志与兼容性说明。
1、首次启用前，在项目设置中开启 Repo Wiki Sync for APIs 功能
2、提交一次含新增接口的代码变更（例如增加 POST /v1/orders）
3、Qoder 自动触发后台任务，识别新增端点、提取 JSDoc 或 XML 注释、生成变更摘要
4、在 Wiki 页面 /wiki/API-Change-Log 中查看最新条目：[ADDED] POST /v1/orders — 创建新订单，支持库存预占与优惠券校验（2026-05-22）
5、点击条目右侧 View Diff 查看该接口在 Swagger JSON 中的原始字段级变更对比
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
