权限管理后端篇(三)之Knife4j注解的使用

Swagger原生注解

1. 注解说明

Swagger的使用注解有很多，这里我们只讲最常用的注解，以及这些注解中最常用的属性。

@Api(tags = {“用户操作”})
加在controller类上
tags表示该类的标签，在页面会独立显示一个菜单
 
@ApiOperation(value = “保存用户”, notes = “保存时，ID由数据库生成，无需填写，有则忽略”, tags = “保存”)
加在相应的请求处理方法上
value表示该方法的说明
notes相当于对该方法的详细说明，也就是更加完整的描述
tags 表示标签，，在页面会独立显示一个菜单
 
@ApiImplicitParam(name = “id”, value = “用户ID”, defaultValue = “1”)
方法只有一个基本类型参数时加在方法上。方法有多个参数时加在@ApiImplicitParams内
name 参数中属性的名字
value 对这个属性的描述
defaultValue 默认值，这个还是有必要填写的，在页面进行请求时，会自动填充
 
@ApiImplicitParams(value = {})
用在请求方法上
这个注解必须和@ApiImplicitParam配合使用
当请求方法中的请求参数很多的时候，例如saveUser(String username, Integer age, Date birthday, String phone)
 
@ApiParam(value = “当前页”, defaultValue = “1”)
加在请求方法的普通参数上
value的值是对该参数的说明
与@ApiImplicitParam使用的效果等同，根据个人喜好进行使用
 
@ApiModel(value = “用户信息”)
加在请求方法的对象类上
value 对该对象参数的描述
例如有一个请求方法save(UserDTO userDTO), 则需要加在UserDTO这个类上面(可以参照下面的示例)
 
@ApiModelProperty(value = “用户ID”, example = “1”)
加在请求方法的参数对象的属性上
value 对该属性的描述
example 属性的示例值，在页面会自动填充该值
 
 
@ApiIgnore：注解类、参数、方法，注解后将不在Swagger UI中显示

使用示例

Controller层注解

@Api(tags = {"用户操作"})
@RestController
@RequestMapping(value = "/user")
public class UserController {
 
    @PostMapping
    @ApiOperation(value = "保存用户", notes = "保存时，ID由数据库生成，无需填写，有则忽略", tags = "保存")
    public ApiResult save(@RequestBody UserDTO userDTO) {
        return ApiResult.success();
    }
 
    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "删除后无法恢复", tags = "删除")
    @ApiImplicitParam(name = "id", value = "用户ID", defaultValue = "1")
    public ApiResult remove(@PathVariable Long id) {
        return ApiResult.success();
    }
 
    @PutMapping
    @ApiOperation(value = "更新用户", notes = "id必填，其它属性存在则更新，否则忽略", tags = "更新")
    public ApiResult update(@RequestBody UserDTO userDTO) {
        return ApiResult.success();
    }
 
    @GetMapping("/{id}")
    @ApiOperation(value = "查找用户", notes = "根据id查找单个用户", tags = "查找")
    public ApiResult find(@PathVariable @ApiParam(value = "用户ID", defaultValue = "2") Long id) {
        return ApiResult.success();
    }
 
    @GetMapping("/list")
    @ApiOperation(value = "查找用户列表", notes = "根据id查找单个用户", tags = "查找")
    public ApiResult list(@RequestParam @ApiParam(value = "当前页", defaultValue = "1") Integer pageNum,
                          @RequestParam @ApiParam(value = "页大小", defaultValue = "10") Integer pageSize) {
        return ApiResult.success();
    }
 
}
 
 

Entity

@Data
@ApiModel(value = "用户实体")
public class UserDTO {
 
    @ApiModelProperty(value = "用户ID", example = "1", required = false)
    private Long id;
 
    @ApiModelProperty(value = "用户名", example = "rose", required = true)
    private String username;
 
    @ApiModelProperty(value = "用户密码", example = "123456", required = true)
    private String password;
 
    @ApiModelProperty(value = "用户年龄", example = "18", allowableValues = "range[1, 150]", required = false)
    private Integer age;
 
    @ApiModelProperty(value = "用户性别", example = "MAN", required = true)
    private GenderEnum gender;
 
}

在2.0.3版本中,收到开发者反馈希望能在Controller上增加作者的注解

所代表的意思是该Controller模块下所有的接口都是该作者负责开发,当然用@ApiOperationSupport的注解也能覆盖

因此,在2.0.3版本中新增加了​​@ApiSupport​​注解,该注解目前有两个属性,分别是author(作者)和order(排序)

使用代码示例：登录后复制 

@Api(tags = "2.0.3版本-20200312")
@ApiSupport(author = "xiaoymin@foxmail.com",order = 284)
@RestController
@RequestMapping("/api/nxew203")
public class Api203Constroller {


}