springfox-swagger2 中的基础注解介绍

springfox-swagger2 可通过注解生成接口文档，包括接口名、请求方法、参数、返回信息等等。常用注解如下：

1. @Api：修饰整个类，描述Controller的作用
2. @ApiOperation：描述一个类的一个方法，或者说一个接口
3. @ApiParam：单个参数描述
4. @ApiModel：用描述实体对象
5. @ApiProperty：用描述实体对象的属性字段
6. @ApiResponse：HTTP响应其中1个描述
7. @ApiResponses：HTTP响应整体描述
8. @ApiIgnore：使用该注解忽略这个API
9. @ApiError ：发生错误返回的信息
10. @ApiImplicitParam：一个请求参数
11. @ApiImplicitParams： 多个请求参数

@Api

@Api()注解用于类，表示标识这个类是swagger的资源 。

@Api(value="用户登录",tags={"用户登录接口"})

1. tags ：表示说明；也用于分组； 需要注意的是当tags有多个值，会对这个类中的所有方法生成多份swagger资源，且每份swagger资源中都包含类中所有的方法（无论方法的@ApiOperation注解的tags属性值是什么）。所以类的此属性不需要指定多个值，最多指定一个值就足够了。如果类中所有方法都有@ApiOperation注解，且每个@ApiOperation注解都有tags属性，则类的@Api()注解可以不指定tags属性，此时会生成一个空的swagger资源，其名称与类名相同。当然，如果有必要的话，也可以指定tags属性，对接口生成按不同维度分组的swagger资源，方便使用。

多数情况下每个@Api注解只需要给出一个tags值就足够了。

2. value ：也是说明，可以使用tags替代 （实际没有作用,可有可无）

@ApiOperation

@ApiOperation注解用于方法，描述一个类的一个方法，或者说一个接口，表示一个http请求的操作。

@ApiOperation(value="", httpMethod = "", response = "接口返回参数类型", notes = "接口发布说明")

1. value：用于方法描述；
2. tags：用于对方法进行分组；如指定多个不同的值，则会在多个不同分组的swagger资源都会出现此接口，更详细的内容可参考@Api()注解下tags属性的说明。
3. notes：用于简短说明，可在特殊情况下对接口进行补充说明，或提示说明。
4. httpMethod：说明HTTP方法，如果使用的@RequestMapping指定了method属性，则可以省略此属性。(注：通常使用@RequestMapping指定了method属性，而省略@ApiOperation的httpMethod属性)
5. response ：说明返回值类型，（无需指定，可自动检测到）