WorkBuddy AI支持四种API文档自动生成方式：一、源码注释提取，需添加Swagger兼容标签并执行生成命令；二、运行时反射捕获，通过actuator端点抓取路由元数据；三、Postman集合导入，自动补全状态码与错误示例；四、CLI离线批量处理，适配CI/CD并输出校验摘要。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜如果您正在使用WorkBuddy AI进行后端服务集成，但尚未生成结构清晰、符合OpenAPI规范的API文档，则可能是由于未正确配置注释规则或未启用自动生成流程。以下是实现接口文档自动输出的多种操作路径：
一、基于源码注释提取生成
该方法利用WorkBuddy AI对代码内嵌注释（如Java的Javadoc、Python的docstring）进行语义解析，自动映射请求路径、参数类型与响应结构。需确保注释中包含明确的HTTP方法、路径、参数说明及示例值。
1、在控制器方法上方添加标准格式注释，例如Java中使用@ApiOperation、@ApiParam等Swagger兼容标签。
2、确认项目已引入workbuddy-ai-doc-plugin依赖，并在构建配置中启用annotation-processing模块。
3、执行mvn clean compile workbuddy:generate-doc命令触发注释扫描与文档合成。
4、生成的YAML文件默认输出至target/docs/openapi.yaml，请勿手动修改该文件，所有变更应反向同步至源码注释。
二、通过运行时反射动态捕获
该方法在服务启动阶段激活WorkBuddy AI的HTTP拦截器，实时监听所有注册的Endpoint，结合Spring MVC或Express路由表自动推导接口契约。适用于无注释或注释不全的遗留系统。
1、在application.yml中设置workbuddy.doc.mode: runtime，并开启actuator端点暴露。
2、启动应用后访问/actuator/workbuddy-docs，触发一次全量路由抓取。
3、系统将返回JSON格式的原始接口元数据，包括path、method、consumes、produces字段。
4、调用POST /api/v1/doc/export?format=swagger2将元数据转换为标准OpenAPI 3.0文档，此过程会忽略未被实际调用过的分支逻辑，建议配合全链路压测使用。
三、接入Postman集合导入转换
该方法适用于已有Postman Collection JSON文件的团队，WorkBuddy AI可将其解析为带校验规则的OpenAPI Schema，并补全缺失的状态码描述与错误示例。
1、导出Postman Collection为v2.1格式JSON文件，确保每个request包含完整headers与body示例。
2、登录WorkBuddy AI控制台，在“文档中心”选择“从集合导入”，上传该JSON文件。
3、系统自动识别变量占位符（如{{base_url}}），并提示映射至环境配置中的对应键名。
4、点击“生成文档”后，生成的HTML页面支持按Tag分组浏览，
所有4xx/5xx响应体结构将依据response body示例自动推断schema，无需手动编写。
四、使用CLI工具离线批量处理
该方法面向CI/CD流水线集成，支持从Git仓库指定分支拉取代码，执行静态分析后直接推送文档至Confluence或GitHub Pages。
1、下载workbuddy-cli-linux-x64（或对应平台版本），赋予执行权限：chmod +x workbuddy-cli。
2、执行./workbuddy-cli --repo-url https://git.example.com/team/api --branch develop --output-dir ./docs。
3、工具自动检测项目语言类型，加载内置模板（Spring Boot/Flask/FastAPI），并跳过test目录下的伪接口。
4、生成完成后，控制台输出文档校验结果摘要，
若出现“missing description for parameter”警告，表示对应参数缺少注释，需返回源码补充。