Swagger 3 已经发布了一段时间了，但是这里我们主要学习目前更主流的 Swagger 2。
Swagger 2 整体注解
- Swagger 2 请求类注解，主要用于 Controller 类上
- Swagger 2 请求方法注解，主要用于 Controller 类对应的方法上
- Swagger 2 对象类注解，主要用于 JavaBean 上
1、Swagger 2 请求类注解
- @Api 标识 Swagger 识别的类
- @Api 放在 @Controller 注解并列的请求类上
- 核心参数包含 value、tags、description
@Api()：用在请求的类上，表示对类的说明，也代表了这个类是 swagger2 的资源，参数：
- tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息。
- value - 字段说明
- description - 注释说明这个类
2、Swagger 2 请求方法注解
- @ApiOperation 标识 Swagger 识别的方法
- @ApiImplicitParam 标识方法的参数的说明
- @ApiResponse 标识方法返回值的说明
@ApiOperation 注解常用属性：
- value：对该操作进行简单的描述，尽量控制在120字符以内。
- notes：对操作的详细描述。
- httpMethod：指定操作使用的HTTP方法类型，可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”。
- tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。实例代码：
@ApiImplicitParam 注解常用属性：
- name：参数名
- value：参数的汉字说明、解释
- required：参数是否必须传
- paramType：参数放在哪个地方
- dataType：参数类型，默认String，其它值dataType=“Integer”
- defaultValue：参数的默认值
@ApiResponse 注解常用属性：
- code：数字，例如400
- message：信息，例如"请求参数不正确"
- response：抛出异常的类
3、Swagger 2 对象类注解
- @ApiModel 标识 Swagger 识别的 JavaBean
- @ApiModel 放在 JavaBean 的类定义上
- @ApiModelProperty 标识 JavaBean 属性
@ApiModel 注解常用属性：
- value：为模型提供备用名称
- description：提供详细的类描述
- parent：为模型提供父类以允许描述继承关系
- discriminatory：支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
- subTypes：从此模型继承的子类型数组
- reference：指定对应类型定义的引用，覆盖指定的任何其他元数据
@ApiModelProperty 注解常用属性：
- value：属性简要说明
- name：运行覆盖属性的名称。重写属性名称
- allowableValues：作用为限制此参数存储的长度
- access：作用为允许从API文档中过滤属性
- notes：作用为该字段的注释说明
- dataType：作用为参数的数据类型
- required：作用为指定参数是否可以为空，默认为false
- position：作用为允许显式地对模型中的属性排序
- hidden：作用为是否允许模型属性隐藏在Swagger模型定义中，默认为false
- example：作用为属性的示例值
- readOnly：作用为是否允许将属性指定为只读，默认为false
- reference：作用为指定对对应类型定义的引用，重写指定的任何其他数据名称
- allowEmptyValue：作用为是否允许传递空值，默认为false
4、总结
