Swagger常用注解详解

Swagger是一个广泛使用的API文档工具，它可以根据代码自动生成API文档，并提供交互式的API测试界面。在Swagger中，注解不仅仅只是用来生成文档，还能够控制API的行为，比如控制参数的校验、控制返回数据的格式、控制API的访问权限等。在本文中，我们将介绍Swagger常用的注解以及它们的使用方法。

一、@Api

@Api注解用来标识一个API的基本信息，包括API的名称、描述、作者等。这些信息将会出现在生成的文档中。@Api注解可以在Controller类上或者方法上使用。

@Api(value = "UserController", tags = {"用户管理"})
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    @PostMapping("/add")
    public Result addUser(@RequestBody User user) {
        //...
    }
}

在上面的示例中，@Api注解用来标识UserController类是一个用来管理用户的Controller，其中"用户管理"是这个API的标签。这个标签会出现在生成的文档中，方便用户查找。

二、@ApiOperation

@ApiOperation注解用来描述一个API的具体操作，包括API的名称、请求方式、请求路径、请求参数、返回结果等。@ApiOperation注解只能在Controller的方法上使用。

@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@PostMapping("/add")
public Result addUser(@Valid @RequestBody User user) {
    //...
}

在上面的示例中，@ApiOperation注解用来描述addUser方法的功能是创建一个用户。其中，value属性是API的名称，notes属性是API的详细描述。@PostMapping注解用来控制请求的HTTP方法，"/add"是请求路径。

三、@ApiParam

@ApiParam注解用来描述一个API的请求参数，包括参数名称、类型、描述、是否必填等。@ApiParam注解只能在Controller的方法的参数上使用。

@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@PostMapping("/add")
public Result addUser(@ApiParam(name = "user", value = "用户实体", required = true) @Valid @RequestBody User user) {
    //...
}

在上面的示例中，@ApiParam注解用来描述请求参数user的具体信息。其中，name属性是参数的名称，value属性是参数的描述，required属性表示该参数是否必填。

四、@ApiResponses

@ApiResponses注解用来描述一个API的可能的返回结果，包括返回状态码、描述信息等。@ApiResponses注解只能在Controller的方法上使用。

@ApiOperation("查询用户")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "请求成功"),
        @ApiResponse(code = 401, message = "未授权"),
        @ApiResponse(code = 403, message = "禁止访问"),
        @ApiResponse(code = 404, message = "请求路径不存在"),
        @ApiResponse(code = 500, message = "服务器内部错误")
})
@GetMapping("/{id}")
public Result getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    //...
}

在上面的示例中，@ApiResponses注解用来描述getUserById方法可能的返回结果。其中，@ApiResponse注解用来描述一个具体的返回结果，包括返回状态码和描述信息。

五、@ApiModelProperty

@ApiModelProperty注解用来描述一个API的返回结果，包括返回对象的名称、类型、描述等。@ApiModelProperty注解只能在DTO类的属性上使用。

@Data
public class UserDTO {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    @ApiModelProperty(value = "用户名", example = "Tom")
    private String username;
    @ApiModelProperty(value = "手机号码", example = "13800138000")
    private String mobile;
}

在上面的示例中，@ApiModelProperty注解用来描述UserDTO类中属性的具体信息。其中，value属性是属性的描述，example属性是属性的样例，方便用户理解。

六、小结

Swagger是一个非常实用的API文档工具，在大型项目中大大简化了API文档的维护和管理。在使用Swagger时，合理使用注解能够帮助我们更好地控制API的行为，生成清晰易懂的API文档。