别再手动写API文档了！用RuoYi+Swagger注解5分钟搞定（含完整Controller示例）-洪萨配资

5分钟极速生成API文档：RuoYi+Swagger全注解实战指南

每次手动维护API文档时，你是否也经历过这样的崩溃时刻？前端同事拿着过时的文档来质问为什么接口返回字段不对，测试人员按旧版文档提交的Bug让你一头雾水，产品经理要求紧急更新文档却赶上迭代截止日...这些场景在采用RuoYi+Swagger组合后将彻底成为历史。本文将手把手带你用注解驱动开发，实现"代码即文档"的终极形态。

1. 环境准备与基础配置

在开始之前，确保你的RuoYi项目已经集成Swagger。现代版本的RuoYi通常已内置Swagger支持，只需检查pom.xml中是否包含以下依赖：

<!-- Swagger核心依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- Swagger UI界面 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>

若需要更美观的界面，可替换为增强版UI：

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>

配置完成后，访问http://localhost:8080/doc.html即可看到文档界面。但空有框架还不够，真正的魔法始于注解的应用。

2. 控制器层注解实战

2.1 类级别注解：@Api

@Api是Swagger在控制器类上的门户注解，相当于给整个模块贴上标签。最佳实践是：

@Api(tags = "用户认证模块") @RestController @RequestMapping("/api/auth") public class AuthController { // 方法实现... }

注意：value属性已过时，现代版本推荐使用tags进行模块分类。同一控制器可设置多个标签，如tags = {"用户模块", "认证中心"}

2.2 方法级别注解：@ApiOperation

每个API方法都需要@ApiOperation注解声明其用途。来看一个用户登录接口的完整示例：

@ApiOperation( value = "用户登录", notes = "通过手机号+密码或第三方授权码登录系统\n" + "1. 首次登录需完成设备验证\n" + "2. 连续失败5次将触发账户锁定", response = LoginResult.class ) @PostMapping("/login") public ResponseEntity<LoginResult> login( @RequestBody @Valid LoginRequest request) { // 实现逻辑... }

关键参数说明：

参数名	类型	必填	说明
value	String	是	接口简短描述
notes	String	否	详细说明，支持Markdown
response	Class	否	成功响应类型

3. 参数描述的艺术

3.1 简单参数：@ApiImplicitParam

对于GET请求或表单参数，推荐使用@ApiImplicitParam：

@ApiOperation("获取用户详情") @ApiImplicitParam( name = "userId", value = "用户唯一标识", required = true, paramType = "path", dataType = "Long", example = "123456" ) @GetMapping("/detail/{userId}") public UserDetail getUserDetail(@PathVariable Long userId) { // 实现逻辑... }

paramType的五大使用场景：

path：RESTful路径参数，如/users/{id}
query：URL查询参数，如?name=value
header：HTTP头参数
form：表单提交参数
body：请求体参数（不推荐在此使用）

3.2 复杂对象：@ApiModel与@ApiModelProperty

当参数为复杂对象时，需要在DTO类上使用模型注解：

@ApiModel("密码修改请求体") public class ChangePasswordRequest { @ApiModelProperty( value = "原密码", required = true, example = "OldPass123!" ) private String oldPassword; @ApiModelProperty( value = "新密码", required = true, notes = "需满足8-20位且包含大小写字母和数字", example = "NewPass456@" ) private String newPassword; // getters & setters }

经验之谈：example属性能极大提升文档可用性，建议为每个字段设置典型示例值

4. 响应与错误处理

4.1 成功响应模板

使用@ApiResponse定义标准响应结构：

@ApiOperation("修改用户信息") @ApiResponses({ @ApiResponse( code = 200, message = "操作成功", response = UserProfile.class ), @ApiResponse( code = 400, message = "参数校验失败", response = ErrorResult.class ) }) @PutMapping("/profile") public ResponseEntity<UserProfile> updateProfile( @RequestBody @Valid UserProfileUpdateRequest request) { // 实现逻辑... }

4.2 全局异常处理

在RuoYi中，可以统一配置异常响应：

@ApiResponse( code = 500, message = "系统内部错误", response = ErrorResult.class ) @ControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(Exception.class) public ResponseEntity<ErrorResult> handleException(Exception ex) { // 异常处理逻辑... } }

5. 高级技巧与避坑指南

5.1 枚举类型处理

对于枚举参数，Swagger能自动识别取值：

@ApiModel("订单查询条件") public class OrderQuery { @ApiModelProperty("订单状态") private OrderStatus status; public enum OrderStatus { @ApiEnum("待支付") PENDING, @ApiEnum("已支付") PAID, @ApiEnum("已取消") CANCELLED } }

5.2 文件上传接口

文件上传需要特殊处理：

@ApiOperation("上传用户头像") @ApiImplicitParams({ @ApiImplicitParam( name = "file", value = "图片文件", required = true, dataType = "__file", paramType = "form" ) }) @PostMapping(value = "/avatar", consumes = "multipart/form-data") public ResponseEntity<String> uploadAvatar( @RequestPart MultipartFile file) { // 实现逻辑... }