WorkBuddy如何生成符合OpenAPI规范文档_解析控制器注释技巧-人工智能-PHP中文网

若api文档缺失路径、参数或响应结构，主因是控制器注释未遵循openapi规范：需用@apioperation等注解标注元信息，启用@enableworkbuddydoc并配置扫描包，再通过workbuddy-doc.yaml补全标题、版本等顶层字段。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

workbuddy如何生成符合openapi规范文档_解析控制器注释技巧

如果您在使用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核心模块严格一致，避免因版本错配导致注解处理器静默失效。

WorkBuddy Visio — Visio 兼容架构图生成器

使用 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则说明扫描失败，需立即检查包路径拼写与类文件编译状态。