Swagger 常用注解使用讲解

讲解内容

1. swagger常用到的注解的解释
2. SpringMVC中控制层类中使用这些注解

swagger常用到的注解的解释

在pom.xml文件中添加包依赖：swagger-annotations-1.5.10.jar

所有注解：

常用到的注解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

Api 标记一个Controller类做为swagger 文档资源

使用方式：

@Api(value = "/user", description = "Operations about user")

与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 将在文档中隐藏

在SpringMvc中的配置如下：

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {
    
}

定义后swagger效果图： 

ApiOperation每一个url资源的定义

使用方式：

@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"})

与Controller中的方法并列使用。

属性配置：

属性名称	备注	默认值
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
notes	对api资源的描述
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
responseReference	可以不配置
httpMethod	可以接受 "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position	如果配置多个Api 想改变显示的顺序位置
produces	同 Api中的定义
consumes	同 Api中的定义
protocols	同 Api中的定义
authorizations	同 Api中的定义
hidden	同 Api中的定义
code	http的状态码 默认 200
extensions	扩展属性

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET)
  @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.class,
      tags = { "Pet Store" })
   public ResponseEntity getOrderById(@PathVariable("orderId") String orderId)
      throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
      return ok(order);
    } else {
      throw new NotFoundException(404, "Order not found");
    }
  }

swagger效果图： 

ApiParam请求属性

使用方式：

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

与Controller中的方法并列使用。

属性配置：

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

在SpringMvc中的配置如下：

 public ResponseEntity getOrderById(
      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
      @PathVariable("orderId") String orderId)

ApiResponse响应配置

使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")	

与Controller中的方法并列使用。 属性配置：

属性名称	备注	默认值
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }

效果图展示： 

ApiResponses相应集配置

使用方式：

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置：

属性名称	备注	默认值
value	多个ApiResponse配置

在SpringMvc中的配置如下：

 @RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }

ResponseHeader相应配置

使用方式：

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置：

属性名称	备注	默认值
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

在SpringMvc中的配置如下：

@ApiModel(description = "群组")

ApiModel相应配置

使用方式：

description="描述实体的作用"  

属性配置：

属性名称	备注	默认值
value	默认为类的名称
description	对该类的描述
parent	可以不配置
discriminator	可以不配置
subTypes	可以不配置
reference	引用配置可以不考虑

在SpringMvc中的配置如下：

@ApiModel(description = "群组")
public class UamGroup {}

ApiModelProperty相应配置

使用方式：

@ApiModelProperty(required = true, value = "群组的Id")

属性配置：

属性名称	备注	默认值
value	属性描述
name	如果配置覆盖属性名称
allowableValues	参考ApiParam配置项项
access	可以不配置
notes	没有使用
dataType	数据类型
required	参考ApiParam配置项项
position	参考ApiOperation配置项
hidden	参考ApiOperation配置项
example	参考ApiParam配置项项
readOnly
reference	参考ApiParam配置项项

在SpringMvc中的配置如下：

@ApiModelProperty(required = true, value = "群组的Id")
    private String groupId;