Springboot整合Swagger常用注解（三）

swagger注解主要是用来给swagger生成的接口文档说明用的

1、@Api

使用范围：用在 类上 注解，控制整个类生成接口信息的内容，表示对类的说明，也代表了这个类是swagger2的资源

参数：

　　tags：说明该类的作用，参数是个数组，可以填多个，在UI视图中就显示几个控制器访问菜单

　　value：该参数没什么意义，在UI界面上不显示，所以不用配置

　　description ：用户基本信息操作，已过时，不建议使用

 

2、@ApiModel

使用范围：用于响应实体类上，用于说明实体作用

参数：

　　value：自定义实体

　　description：详细描述实体的作用

3、@ApiModelProperty：

使用范围：用在属性上，描述实体类的属性

参数：
　　name：字段别名
　　value：字段描述
　　required：是否是必须字段
　　example：示例数据
　　hidden：是否隐藏数据

 

4、@ApiOperation

使用范围：用于方法，表示一个http请求访问该方法的操作

参数：

　　value：说明方法的用途和作用
　　notes：方法的注意事项和备注说明
　　tags：说明该方法的作用，参数是个数组，可以填多个。
　　格式：tags={"作用1","作用2"}
　　（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

 

5、@ApiParam

使用范围：用于方法，参数，字段说明 表示对参数的要求和说明

参数：

　　name：参数别名
　　value：参数的描述
　　required： 表示属性是否必填，默认为false

　　defaultValue：参数默认值

 

6、@ApiIgnore

使用范围：忽略，当前注解描述的方法或类型，不生成api文档

 

7、@ApiImplicitParams

使用范围：使用在方法上，描述方法的一组参数

参数：

　　value：是@ApiImplicitParam类型的数组

8、@ApiImplicitParam：

使用范围：使用在方法上，描述方法的单个参数

参数：

　　name：参数名称
　　value：参数说明
　　dataType：数据类型
　　paramType：参数类型

　　　　.query 表示参数放在哪里
　　　　· header 请求参数的获取：@RequestHeader
　　　　· query 请求参数的获取：@RequestParam
　　　　· path（用于restful接口） 请求参数的获取：@PathVariable
　　　　· body（不常用）
　　　　· form（不常用）
　　defaultValue：参数的默认值
　　required：true表示参数是否必须传

 

9、@ApiResponses

使用范围：用于请求的方法上，根据响应码表示不同响应

10、@ApiResponse

使用范围：用在请求的方法上，表示不同的响应

参数：

　　code="404" 表示响应码(int型)，可自定义
　　message="状态码对应的响应信息"

　　response：抛出异常的类

 

11、@Profile({"dev", "test"})：

使用范围：用于配置类上，表示只对开发和测试环境有用

12、

@Authorization：声明要在资源或操作上使用的授权方案
@AuthorizationScope：描述OAuth2授权范围
@ResponseHeader：表示可以作为响应的一部分提供的标头
@ApiProperty：描述POJO对象中的属性值
@ApiError：接口错误所返回的信息