猿导航

Swagger 常用注解

Swagger 常用注解

@Api 类级别

与Controller注解并列使用。 属性配置：

属性名称 备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏 
/**
 * @program: artwork
 * @description
 * @author: FMm
 * @date: 2020/10/24 10:50 PM
 **/
@RestController
@RequestMapping("/system/index")
@Api( description = "主控制层",tags = "测试description")
public class IndexController {

}

@ApiOperation 方法级别 与Controller中的方法并列使用。

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})
属性名称 备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http的状态码 默认 200
extensions 扩展属性

@ApiParam

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置：

属性名称 备注
name 属性名称
value 属性值
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为false
hidden 隐藏该属性
example 举例子

@ApiImplicitParams：用在方法上包含一组参数说明；

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

  • paramType：参数放在哪个地方
  • name：参数代表的含义
  • value：参数名称
  • dataType： 参数类型，有String/int，无用
  • required ： 是否必要
  • defaultValue：参数的默认值

@ApiResponses：

用于表示一组响应；

@ApiResponse：

用在@ApiResponses中，一般用于表达一个错误的响应信息；

  • code： 响应码(int型)，可自定义
  • message：状态码对应的响应信息

@ApiModel：

描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@ApiModelProperty：

描述一个model的属性。