swagger常用注解说明

1、与模型相关的注解,用在bean上面

@ApiModel：用在bean上，对模型类做注释；
　　　　@ApiModelProperty：用在属性上，对属性做注释

2、与接口相关的注解

@Api：用在controller上，对controller进行注释；
　　　　@ApiOperation：用在API方法上，对该API做注释，说明API的作用；
　　　　@ApiImplicitParams：用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明；
　　　　@ApiImplicitParam：用在@ApiImplicitParams注解中，也可以单独使用，说明一个请求参数的各个方面，该注解包含的常用选项有：
　　　　　　paramType：参数所放置的地方，包含query、header、path、body以及form，最常用的是前四个。
　　　　　　name：参数名；
　　　　　　dataType：参数类型，可以是基础数据类型，也可以是一个class；
　　　　　　required：参数是否必须传；
　　　　　　value：参数的注释，说明参数的意义；
　　　　　　defaultValue：参数的默认值；
　　　　
　　　 @ApiResponses：通常用来包含接口的一组响应注解，可以简单的理解为响应注解的集合声明；
　　　 @ApiResponse：用在@ApiResponses中，一般用于表达一个响应信息
　　　　　　code：即httpCode，例如400
　　　　　　message：信息，例如"操作成功"
　　　　　　response = UserVo.class 这里UserVo是一个配置了@ApiModel注解的对像，该是对像属性已配置 @ApiModelProperty,swagger可以通过这些配置，生　成接口返回值

注意事项:

为了在swagger-ui上看到输出，至少需要两个注解：@Api和@ApiOperation
即使只有一个@ApiResponse，也需要使用@ApiResponses包住

对于@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam获取， header域中的值需要使用@RequestHeader来获取，path域中的值需要使用@PathVariable来获取，body域中的值使用@RequestBody来获取，否则可能出错；而且如果paramType是body，name就不能是body，否则有问题，与官方文档中的“If paramType is “body”, the name should be "body"不符。

常用注解：

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明：
@Api()
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list

@ApiOperation() 用于方法；表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明