Knife4j常用注解

发布时间 2023-08-21 11:03:57作者: 林林2127

Knife4j注解说明

1. @Api

添加在控制器类上,通过此注解的tags属性,可以指定模块名称,并且,在指定名称时,建议在名称前添加数字作为序号,Knife4j会根据这些数字将各模块升序排列,例如:

@Api(value = "提供商品添加、修改、删除及查询的相关接⼝",tags = "01.商品管理")

2. @ApiOpearation

添加在Api中处理请求的方法上,通过此注解的value属性,可以指定业务/请求资源的名称,例如:

@ApiOperation("添加商品")

3. @ApiOperationSupport

添加在Api中处理请求的方法上,通过此注解的order属性(int),可以指定排序序号,Knife4j会根据这些数字将各业务/请求资源升序排列,例如:

@ApiOperationSupport(order = 100)

4. @ApiImplicitParams 和 @ApiImplicitParam

对于处理请求的方法的参数列表中那些未封装的参数(例如String、Long),需要在处理请求的方法上使用此注解来配置参数的说明,并且,必须配置name属性,此属性的值就是方法的参数名称,使得此注解的配置与参数对应上,然后,再通过value属性对参数进行说明,还要注意,此属性的required属性表示是否必须提交此参数,默认为false。另外,还可以通过dataType配置参数的数据类型,如果未配置此属性,在API文档中默认显示为string,可以按需修改为int、long等。例如:

@ApiImplicitParams({
 @ApiImplicitParam(dataType = "string",name = "username", value = "⽤户登录账号",required =
true),
 @ApiImplicitParam(dataType = "string",name = "password", value = "⽤户登录密码",required =
false,defaultValue = "111111")
})

5. @ApiModel

用来对实体类进行说明,例如:

@ApiModel(value = "User对象",description = "⽤户信息")

6. @ApiModelProperty

作用在实体类的参数上,如果处理请求时,参数是封装的POJO类型,需要对各请求参数进行说明时,应该在此POJO类型的各属性上使用此注解,通过此注解的value属性配置请求参数的名称,通过requeired属性配置是否必须提交此请求参数(并不具备检查功能),例如:

@ApiModelProperty(dataType = "String",required = true, value = "⽤户注册账号")

注:此注解只有在Api接口中使用封装的POjO类型作为参数时才会生效。