若API文档缺失路径、参数或响应结构，主因是控制器注释未遵循OpenAPI规范：需用@ApiOperation等注解标注元信息，启用@EnableWorkBuddyDoc并配置扫描包，再通过workbuddy-doc.yaml补全标题、版本等顶层字段。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用WorkBuddy生成API文档时发现接口路径缺失、参数未标注或响应体结构混乱，则很可能是控制器中注释未按OpenAPI语义规范书写。以下是依据源码注释自动生成标准OpenAPI文档的关键操作步骤：
一、规范使用结构化注解标注接口元信息
WorkBuddy依赖@ApiOperation、@ApiParam等注解提取接口语义，若仅用普通JavaDoc或缺失required属性，将导致字段不可见或校验逻辑失效。
1、在Controller方法上方添加@ApiOperation注解，value属性填写简洁业务名称，notes属性描述完整行为与副作用，例如：@ApiOperation(value = "创建用户", notes = "接收用户基本信息，返回含ID的完整对象，成功时HTTP状态码为201")。
2、对每个@RequestParam参数添加@ApiParam注解，显式声明required = true或required = false，并通过value属性说明业务含义与格式约束，例如：@ApiParam(required = true, value = "手机号，11位数字，需通过运营商三要素验证") String phone。
3、对@RequestBody参数类，在其字段上逐个添加@ApiModelProperty注解，设置value、example、allowEmptyValue等属性，确保生成的Schema包含可读示例与空值策略。
4、在方法返回类型上方添加@ApiResponse注解，针对不同HTTP状态码分别定义，例如：@ApiResponse(code = 201, message = "创建成功", response = User.class) 和 @ApiResponse(code = 400, message = "参数校验失败", response = ValidationError.class)。
二、统一启用注解驱动并校验扫描范围
即使注解书写完整，若框架未激活扫描机制或包路径配置错误，WorkBuddy仍将无法识别任何接口信息。
1、确认项目pom.xml中已引入workbuddy-swagger-starter依赖，且版本号与当前WorkBuddy核心模块严格一致，避免因版本错配导致注解处理器静默失效。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
2、检查主启动类是否添加@EnableWorkBuddyDoc注解，该注解是触发自动装配的必要开关，缺省状态下所有注解均被忽略。
3、验证application.properties中workbuddy.doc.base-packages配置项是否覆盖全部Controller所在包，例如：workbuddy.doc.base-packages=com.example.api.controller,com.example.module.user.controller。
4、启动应用后访问/wb-doc端点，查看页面右上角显示的“已加载接口数”，若为0则说明扫描失败，需立即检查包路径拼写与类文件编译状态。
三、注入YAML全局元数据以补全OpenAPI顶层结构
单纯依赖代码内注解只能生成接口级信息，缺少标题、版本、许可证等OpenAPI根对象必需字段，必须通过外部YAML注入补全。
1、在resources目录下新建workbuddy-doc.yaml文件，确保其编码为UTF-8且无BOM头。
2、写入以下三项强制字段：title必须非空、version必须符合语义化版本格式（如v1.2.0）、contact.name必须明确指定负责人或团队名称。
3、在application.properties中添加配置：workbuddy.doc.config-location=classpath:workbuddy-doc.yaml，路径必须精确到文件名，不支持通配符或相对上级路径。
4、重启服务后，/wb-doc生成的JSON文档根节点将包含info字段，其内容完全来自该YAML，任何缺失字段都将导致OpenAPI验证失败。
