swagger注解类使用说明

原创
2016/11/24 15:10
阅读数 3.1W

讲解内容

  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<Order> 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<User> 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<Order> 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<String> 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<String> 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相应配置

使用方式:


属性配置:

属性名称 备注 默认值
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;
展开阅读全文
打赏
4
13 收藏
分享
加载中
打赏
0 评论
13 收藏
4
分享
返回顶部
顶部