需启用注释识别插件、规范编写语义化注释、执行cli导出markdown、内置服务发布swagger ui、配置git预提交钩子，实现从代码注释到结构化接口文档的全流程自动化。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 Qoder 进行开发时，希望将代码中已有的注释直接转化为结构化、可交付的接口文档，则需依赖其对注释语义的深度解析能力与多格式导出机制。以下是实现该目标的具体操作路径：
一、启用 Qoder 的注释识别与文档生成插件
Qoder 默认不自动激活文档生成功能，需手动开启对应模块以识别 @pathParam、@queryParam、@bodyParam 等语义化标签，并将其映射为 OpenAPI v3 元数据。该步骤确保后续导出内容具备完整参数位置、类型、必填性及示例信息。
1、打开 Qoder 设置面板，进入 Plugins → Documentation Generator 子页。
2、勾选 Enable OpenAPI 3 Schema Extraction 和 Parse JSDoc/Q#-style XML Comments 两项开关。
3、在 Supported File Extensions 中添加 .ts, .js, .qsharp, .php，覆盖主流后端与量子语言文件类型。
二、规范编写可被识别的代码注释
Qoder 文档生成器仅提取符合特定语法结构的注释块，忽略自由格式描述。必须使用标准化参数标记，否则字段将被跳过或类型丢失，导致 Swagger UI 中缺失请求体或响应结构。
1、在函数/操作上方插入三斜线注释块（如 Q#）或 JSDoc 块（如 TypeScript），且首行必须含 @api 或 @endpoint 标签声明接口路径。
2、为每个参数显式标注来源：使用 @pathParam userId int "用户唯一标识" 表示 URL 路径变量；使用 @queryParam limit number "分页数量" [10] 表示查询字符串参数并带默认值；使用 @bodyParam payload object "创建订单请求体" required 标记 JSON 请求体字段及其必填状态。
3、在注释末尾添加 @example {"name":"test","price":99.9} 块，Qoder 将其渲染为 Markdown 中的代码示例或 Swagger 的 try-it-out 示例请求体。
三、执行命令行一键导出 Markdown 文档
Qoder CLI 提供轻量级本地导出能力，无需启动 IDE 或连接云端服务，适用于 CI 流程集成与离线文档快照生成。输出结果为纯文本 Markdown，保留表格结构、代码块缩进与参数分类层级。
1、在项目根目录下执行：qoder doc generate --format markdown --output docs/api.md。
2、确认控制台输出 [SUCCESS] Generated 12 endpoints into docs/api.md，表示全部路由注释已成功解析。
3、检查生成文件中是否包含标准四列表格：参数名、位置（Path/Query/Body）、类型、说明，且 required 字段在“说明”列中标有 必填 标识。
四、通过内置服务发布交互式 Swagger UI
Qoder 内置轻量 HTTP 服务可将当前项目注释实时编译为 OpenAPI 3.0 JSON，并挂载 Swagger UI 页面，支持在线调试、鉴权测试与请求体自动填充，适合联调阶段快速验证接口契约。
1、运行指令：qoder doc serve --port 8081，服务启动后监听本地 8081 端口。
2、浏览器访问 http://localhost:8081/swagger，加载完成即显示所有已识别接口分组与展开面板。
3、点击任一接口的 Try it out 按钮，观察请求体字段是否与 @bodyParam 注释完全一致，包括嵌套对象结构与示例值。
五、配置自动化钩子实现提交即更新文档
为避免文档滞后于代码变更，可在 Git 提交前注入预处理脚本，强制校验注释完整性并刷新文档文件。该机制通过 Qoder 的 hook 系统绑定，不依赖外部构建工具链。
1、在项目根目录创建 .qoder/hooks/pre-commit.mjs 文件，写入调用 qoder doc validate --strict 的逻辑。
2、启用严格模式后，若某接口缺少 @bodyParam 类型声明或 @api 路径未匹配实际路由，提交将被中断并提示具体文件与行号。
3、在钩子末尾追加 qoder doc generate --format markdown --output docs/latest.md，确保每次合法提交均同步最新文档版本。
