属性配置: 属性名称备注 value url的路径值 tags 如果设置这个值、value的值会被覆盖 descrip

时间:2021-11-24 04:54:11

常用到的注解有:

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 = storeData.get(Long.valueOf(orderId)); if (null != order) { return ok(order); } else { throw new NotFoundException(404, "Order not found"); } } 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   举例子