springfox-swagger2 中的基础注解介绍
2019-02-15 本文已影响39人
JSON_NULL
springfox-swagger2 可通过注解生成接口文档，包括接口名、请求方法、参数、返回信息等等。常用注解如下：
-
@Api：修饰整个类，描述Controller的作用 -
@ApiOperation：描述一个类的一个方法，或者说一个接口 -
@ApiParam：单个参数描述 -
@ApiModel：用描述实体对象 -
@ApiProperty：用描述实体对象的属性字段 -
@ApiResponse：HTTP响应其中1个描述 -
@ApiResponses：HTTP响应整体描述 -
@ApiIgnore：使用该注解忽略这个API -
@ApiError：发生错误返回的信息 -
@ApiImplicitParam：一个请求参数 -
@ApiImplicitParams： 多个请求参数
@Api
@Api()注解用于类，表示标识这个类是swagger的资源 。
@Api(value="用户登录",tags={"用户登录接口"})
-
tags：表示说明；也用于分组； 需要注意的是当tags有多个值，会对这个类中的所有方法生成多份swagger资源，且每份swagger资源中都包含类中所有的方法（无论方法的@ApiOperation注解的tags属性值是什么）。所以类的此属性不需要指定多个值，最多指定一个值就足够了。如果类中所有方法都有@ApiOperation注解，且每个@ApiOperation注解都有tags属性，则类的@Api()注解可以不指定tags属性，此时会生成一个空的swagger资源，其名称与类名相同。当然，如果有必要的话，也可以指定tags属性，对接口生成按不同维度分组的swagger资源，方便使用。
多数情况下每个@Api注解只需要给出一个tags值就足够了。
-
value：也是说明，可以使用tags替代 （实际没有作用,可有可无）
@ApiOperation
@ApiOperation注解用于方法，描述一个类的一个方法，或者说一个接口，表示一个http请求的操作。
@ApiOperation(value="", httpMethod = "", response = "接口返回参数类型", notes = "接口发布说明")
-
value：用于方法描述； -
tags：用于对方法进行分组；如指定多个不同的值，则会在多个不同分组的swagger资源都会出现此接口，更详细的内容可参考@Api()注解下tags属性的说明。 -
notes：用于简短说明，可在特殊情况下对接口进行补充说明，或提示说明。 -
httpMethod：说明HTTP方法，如果使用的@RequestMapping指定了method属性，则可以省略此属性。(注：通常使用@RequestMapping指定了method属性，而省略@ApiOperation的httpMethod属性) -
response：说明返回值类型，（无需指定，可自动检测到）
