启用WorkBuddy自动文档生成功能需五步：一、添加依赖并启用注解驱动；二、配置YAML全局元数据；三、注入动态响应示例；四、导出OpenAPI 3.0文件；五、定制接口分组与排序。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您使用WorkBuddy开发后端服务，但尚未生成符合团队协作与第三方集成要求的API文档，则可能是由于未启用其基于代码逻辑的自动文档生成功能。以下是为WorkBuddy项目编写标准API接口文档的具体操作路径：
一、启用注解驱动的自动文档生成
WorkBuddy支持通过结构化注解（如@ApiOperation、@ApiParam）在源码中声明接口语义，框架据此提取路径、参数、响应体等元信息并渲染为标准文档。需确保项目已集成兼容的文档插件并正确配置扫描包路径。
1、在Spring Boot项目的pom.xml中添加workbuddy-swagger-starter依赖，版本号需与当前WorkBuddy核心模块对齐。
2、在主启动类上添加@EnableWorkBuddyDoc注解，显式开启文档自动装配能力。
3、在Controller类的每个方法上方，使用@ApiOperation(value = "用户登录", notes = "接收用户名密码，返回JWT令牌")标注业务意图。
4、对所有@RequestParam、@RequestBody参数分别添加@ApiParam(required = true, value = "长度6-20位的登录账号")说明约束条件。
二、配置YAML格式的全局文档元数据
WorkBuddy允许通过外部YAML文件定义API文档的标题、版本、联系人、许可证等顶层信息，避免硬编码污染业务代码，同时支持多环境差异化配置。
1、在resources目录下创建workbuddy-doc.yaml文件。
2、写入title: "用户中心服务API"、version: "v2.3.1"、contact.name: "后端架构组"三行关键字段。
3、将yaml文件路径通过application.properties中的workbuddy.doc.config-location=classpath:workbuddy-doc.yaml指定。
4、重启应用后，/wb-doc路径下生成的HTML文档页眉将同步显示该YAML中声明的元数据。
三、运行时注入动态示例值
WorkBuddy在解析@ApiResponse注解时，可结合自定义ExampleProvider类为每个HTTP状态码生成真实格式的响应体样例，替代默认的空对象占位符，提升前端联调效率。
1、新建UserLoginSuccessExample类，实现WorkBuddy提供的IExampleProvider接口。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
2、重写getExample()方法，返回new LoginResponse("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")构造的实例。
3、在登录方法的@ApiResponse中添加responseContainer = UserLoginSuccessExample.class参数。
4、访问/wb-doc页面时，200响应区块右侧的"Example Value"标签页将展示该类生成的JWT字符串。
四、导出离线OpenAPI 3.0规范文件
WorkBuddy内置OpenAPI 3.0转换器，可将运行时聚合的接口元数据序列化为标准JSON/YAML格式，满足CI/CD流程中自动化测试、Mock服务部署等下游环节需求。
1、确保application.properties中设置workbuddy.doc.export-openapi=true。
2、启动应用后，向GET /wb-doc/openapi.json发起请求。
3、响应体即为完整OpenAPI 3.0规范的JSON文本，包含paths、components、servers等全部必需字段。
4、将返回内容保存为openapi.json文件，可直接导入Postman或Swagger Editor进行可视化验证。
五、定制化接口分组与排序策略
WorkBuddy默认按Controller类名首字母排序接口列表，但可通过@ApiTag注解强制指定分组名称及显示顺序，使文档结构更贴合业务域划分习惯。
1、在UserController类顶部添加@ApiTag(name = "5-用户管理", order = 5)注解。
2、在OrderController类顶部添加@ApiTag(name = "2-订单处理", order = 2)注解。
3、重启服务后，/wb-doc页面左侧导航栏按order数值升序排列，且分组标题显示为name属性值。
4、注意：order值必须为整数，相同order的分组将按类名二次排序。
