swagger常⽤注解说明
常⽤到的注解有：
Api
ApiModel
ApiModelProperty
ApiOperation
ApiParam
ApiResponse
ApiResponses
ResponseHeader
1. api标记
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 {
}
2. ApiOperation标记
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的值会被覆盖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扩展属性
在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 = (Long.valueOf(orderId));
if (null != order) {
return ok(order);
} else {
throw new NotFoundException(404, "Order not found");
}
springmvc面试题常用注解}
3. ApiParam标记
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举例⼦
在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)
4. ApiResponse
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("");
}
5. ApiResponses
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("");
}
6. ResponseHeader
响应头设置，使⽤⽅法
@ResponseHeader(name="head1",description="response head conf")
与Controller中的⽅法并列使⽤。属性配置：
属性名称备注
name响应头名称
description头描述
response默认响应类 Void
responseContainer参考ApiOperation中配置
在SpringMvc中的配置如下：
@ApiModel(description = "组")
7. 其他
@ApiImplicitParams：⽤在⽅法上包含⼀组参数说明；
@ApiImplicitParam：⽤在@ApiImplicitParams注解中，指定⼀个请求参数的各个⽅⾯
paramType：参数放在哪个地⽅
name：参数代表的含义
value：参数名称
dataType：参数类型，有String/int，⽆⽤
required ：是否必要
defaultValue：参数的默认值
@ApiResponses：⽤于表⽰⼀组响应；
@ApiResponse：⽤在@ApiResponses中，⼀般⽤于表达⼀个错误的响应信息；
code：响应码(int型)，可⾃定义
message：状态码对应的响应信息
@ApiModel：描述⼀个Model的信息（这种⼀般⽤在post创建的时候，使⽤@RequestBody这样的场景，请求参数⽆法使⽤@ApiImplicitParam注解进⾏描述的时候；
@ApiModelProperty：描述⼀个model的属性。
作者：Xiangdong_She
链接：www.jianshu/p/12f4394462d5
來源：简书
著作权归作者所有。商业转载请联系作者获得授权，⾮商业转载请注明出处。

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。