通常我们在controller类会这么使用swagger
@Api(value = "Xxx管理", tags = "Xxx管理")
@Slf4j
@RestController
@RequestMapping("/xxx")
public class XxxController {
@Autowired
private IXxxService xxxService;
@ApiOperation(value = "分页查询列表", tags = "Xxx管理")
@RequestMapping(value = "/listPage", method = RequestMethod.POST)
public Result listPage(@RequestBody PageParam queryParam) {
//查询逻辑...
return Result.ok(page);
}
@ApiOperation(value = "添加", tags = "Xxx管理")
@RequestMapping(value = "/add", method = RequestMethod.POST)
public Result add(@RequestBody @Validated Xxx param) {
//添加逻辑...
return Result.ok(xxxService.saveXxx(param));
}
@Api注解用于描述类,@ApiOperation注解用于描述方法。两种注解都有value、tags属性,那么这两个属性的区别是什么?作用在类上 和 作用在方法上又有什么区别?
1、注解属性value、tags二者的区别?
value属性用于描述,tags用于分组。
2、注解属性value、tags二者作用在类和作用在方法上的区别?
①、value属性作用在类和作用在方法上都用于描述;
②、tags属性作用在类和作用在方法上都用于分组,但分组的效果区别很大。
a、tags作用在类上时,会对全局的方法分组,即根据tags属性值复制多份,此时方法上的tags值无效,方法上tags配或不配效果都一样。
b、tags作用在方法上时,会根据当前类的所有方法的tags值做分组,粒度更细。
总结: a、b两种都有使用场景,可以根据业务需要做选择。
扩展:
@ApiOperation() 用于方法;表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组
@ApiParam() 用于方法的参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
name–参数名
value–参数说明
required–是否必填
@ApiModel() 用于类 ;表示对类进行说明,用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty() 用于类的字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@ApiIgnore() 用于类或者方法上,可以不被swagger显示在页面上