一、常用注解说明
1、@Api
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看不到,所以不需要配置"
2、@ApiOperation
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
3、@ApiImplicitParams
1)注解基础说明
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
2)@ApiImplicitParam属性dataType单独使用会出现的bug说明
- 问题描述
如果你的项目模块,swagger配置了分组,如下图
其效果
这时,swagger有一个非常坑的bug:你的注解@ApiImplicitParam属性dataType,不能单独使用,否则会引起一个前端错误、导致当前分组Api文档无法显示(页面会停留在点击前的页面、不跳转)。
bug截图
- 解决方式
如果要设置分组,那么使用@ApiImplicitParam注解时,dataType属性要么不使用,要么就和paramType属性一起使用
这个应该时swagger的一个bug,并没有逻辑性,我是通过一次一次测试得到的结果。(花了整整一天时机做这种没意义的事,希望大家不用重蹈覆辙~)
下面把测试截图记录一下,当时已知name和value属性是干净的,dataType单独使用不行、必须和paramType组合使用:
a、怀疑是dataType位置导致的,做以下测试,发现bug没有修复;
b、又想是不是dataType和required属性组合也可以,做以下测试,bug没有修复
b、经测试,配置分组后@ApiImplicitParam注解的dataType属性就只能和paramType属性一起使用,或者不使用;单独使用就会引发上述错误。与属性先后顺序(位置)无关。
3.5、@ApiImplicitParams常用配套参数@ApiIgnore和@ApiModelProperty属性hidden
1)痛点
使用@ApiImplicitParam注解备注参数后,文档会有这样的问题:就是注解的备注会显示,方法形参也会显示(名称相同就显示一个)。这样会导致api文档特别冗余,很难读、还容易引发歧义,而且与我们的初衷也不相符,我都用@ApiImplicitParam注解了,肯定是希望以注解的备注为准啊,形参的显示混淆了视听。
2)解决
这时我们肯定想,其实不是入参的字段在swagger文档中隐藏掉;可以用以下几种方法。(隐藏,是指不在swagger接口文档中显示)
a、使用@ApiIgnore注解(最简单实用)
该注解用在方法的形参列表,它会将其后的参数隐藏掉;如果注解后是一个实体类,那么该实体类的所有字段都会被隐藏。
b、使用@ApiModelProperty的hidden属性
如果你的接口参数是用实体类接收的,那么你可以在字段上使用@ApiModelProperty注解,并将其属性hidden值设为true,这样该字段就会在swagger文档上隐藏了。
但是这个方法有个问题,当实体类字段特别多时,那你就需要加非常多@ApiModelProperty注解才能把它们全部隐藏。
不过它也有适用场景,当你不用@ApiImplicitParam注解备注接口入参、就用@ApiModelProperty注解备注时,你就可以用hidden属性将实体类中不是入参的其他字段隐藏掉。
4、@ApiModel
@ApiModel:用于类,表示对类进行说明,用于参数用实体类接收
value:表示对象名
description:描述
5、@ApiModelProperty
@ApiModelProperty:用于字段; 表示对model属性的说明或者数据操作更改
value:字段说明
name:重写属性名字(实测没什么用,seagger会自动强制写属性名)
dataType:重写属性类型 (也没什么用,seagger会自动强制写属性类型)
required:是否必填,Boolean类型,默认flase(必填字段会有个*)
example:举例说明(可以给一个字段值示例)
hidden:是否隐藏,Boolean类型,默认flase
6、@ApiModel
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性