讲解内容
swagger常用到的注解的解释
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相应配置
使用方式：
属性配置：
属性名称
备注
默认值
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;