Swagger 常用注解

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

1. @Api

• @Api：是类上注解，控制整个类生成接口信息的内容
  • tags：类的名称，可以有多个值，多个值表示多个副本，在UI视图中就显示几个控制器访问菜单
  • description：描述，已过时
    

2. @ApiOperation

• @ApiOperation：方法的说明，value值必须提供
  • value：说明方法的作用
  • notes：方法的备注说明
    

3. @ApiParam

• @ApiParam：可以作用于方法参数和成员变量
  • name：参数别名
  • value：参数的描述
  • required：是否必须需要
    

4. @ApiIgnore

• @Apilgnore：忽略，当前注解描述的方法或类型，不生成api文档

5. @ApiImplicitParam和@ApiImplicitParams

• @ApiImplicitParam：使用在方法上，描述方法的单个参数
  • name：参数名称
  • value：描述
  • required：是否必要参数
  • paramType：参数类型
  • dataType：数据类型
• @ApiImplicitParams：使用在方法上，描述方法的一组参数
  • value：是@ApiImplicitParam类型的数组
    

6. @ApiModel和@ApiModelProperty

• @ApiModel：描述一个实体类型，这个实体类型如果成为任何一个生成api帮助文档方法的一个返回值类型的时候，此注解被解析
  • value：自定义实体
  • description：详细描述
• @ApiModelProperty：实体类属性描述
  • name：字段别名
  • value：字段描述
  • required：是否是必须字段
  • example：示例数据
  • hidden：是否隐藏数据

7. @ApiResponse和@ApiResponses

@ApiResponses、@ApiResponse方法返回值的说明

• @ApiResponses：方法返回对象的说明
• @ApiResponse：每个参数的说明
  • code：数字，例如：300
  • message：信息，例如：”请求参数没填好"
  • response：抛出异常的类

8. 其他注解

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