API文档未能自动生成？遇到这类问题该如何解决？
在实际开发中，许多团队常遇到一个典型问题：接口开发完成后，发现QoderWake并未自动生成可供交付的API文档。这种情况通常源于几个方面——API文档生成模块未被开启、OpenAPI规范上下文未成功注入、或者目标服务端点未能被正确识别。下面将提供四种可操作的解决方案，帮助将代码变更与接口定义同步转化为结构化的API文档。
一、启用QoderWake内置的OpenAPI文档生成引擎
该方案依托QoderWake对Spring Boot、FastAPI、Express等主流框架的AST语义解析能力，能够自动提取路由路径、请求方法、参数类型、响应结构及异常码，最终生成符合OpenAPI 3.0规范的YAML或JSON格式文档。整个流程的关键在于源码中的注解（例如@Operation、@ApiResponse）或类型提示（如Pydantic模型）充当元数据源。
具体操作简单明了：
第一步：在IDE中打开包含REST接口定义的源文件，确保光标位于控制器类或路由函数上。
第二步：右键弹出菜单，依次选择QoderWake → Generate OpenAPI Spec选项。
第三步：等待状态栏显示“Parsing endpoint signatures…”提示，约2秒后系统会自动生成openapi.yaml文件，并预览关键路径。
第四步：若首次未触发生成，请前往QoderWake设置页面确认Enable OpenAPI Generator已勾选，并将Framework Detection Mode设为Auto。
二、通过QoderCLI命令行批量导出服务级API文档
该方案更适合集成到CI/CD流水线中，或用于微服务集群统一归档的场景。它支持从指定的Git Tag或运行时服务端点拉取Swagger UI资源，经过标准化清洗后，输出带有版本号、服务标识及变更摘要的API文档包。
操作步骤：
1. 在终端中切换到项目根目录，执行命令：qoder-cli apidoc --from-service http://localhost:8080/v3/api-docs --output ./docs/openapi/。
2. 检查输出目录下生成的user-auth-v2.4.0-openapi.yaml文件，确认其中包含info.version、servers以及全部paths区块。
3. 若发现缺少认证描述，可运行qoder-cli config set apidoc.auth.enrichment=enabled开启鉴权字段增强模式。
4. 最后执行git add ./docs/openapi/*.yaml && git commit -m "chore: auto-publish API spec from QoderWake"完成版本归档。
三、绑定Repo Wiki联动生成带用例说明的交互式文档
此方法将QoderWake与Repo Wiki知识图谱深度耦合，不仅生成基础的OpenAPI文档，还会自动注入业务场景用例、调用链路截图、Mock响应示例及历史兼容性标注，最终形成面向前端及测试团队的交互式文档站点。
具体配置：
1. 打开Qoder桌面端，进入当前项目Workspace，点击左上角「Settings」→「API Documentation」。
2. 启用「Sync with Repo Wiki」，并选择Wiki空间ID为“platform-api-catalog”。
3. 在「Use Case Enrichment」区域勾选「Inject sample request/response」和「Link to related test cases」。
4. 保存配置后，每次保存包含@RequestBody或@Schema注解的接口文件，系统将自动同步更新Wiki页面中对应的API节点。
四、配置Git Pre-push Hook自动校验并提交API文档
该方案基于Harness-First架构中的验证规则维度，在代码推送前强制执行API契约一致性检查。只有文档成功生成并通过OpenAPI Validator验证，才允许推送，从而确保接口定义与实现严格对齐。
配置流程：
1. 在项目根目录执行：qoder repo hook install --type pre-push --action validate-openapi。
2. 系统会自动生成.git/hooks/pre-push脚本，其中嵌入了qoder-cli apidoc --validate --strict指令。
3. 修改任意接口后尝试git push，若openapi.yaml缺失或存在$ref循环引用，推送将中断并提示具体错误位置。
4. 修复后重新运行qoder-cli apidoc --write生成合规文档，即可正常推送。