Swagger common annotation description

Forward: Author Xiangdong_She

Author link: http://www.jianshu.com/p/12f4394462d5

Commonly used annotations are:

Api
ApiModel
ApiModelProperty
ApiOperation
apiParam
ApiResponse
ApiResponses
ResponseHeader

api标记

Api markup can mark a Controller class as a swagger document resource, using:
@Api(value = "/user", description = "Operations about user")

Used in parallel with the Controller annotation. Property configuration:

property name	Remark
value	url's path value
tags	If this value is set, the value of value will be overwritten
description	description of the api resource
basePath	The base path can not be configured
position	If you configure multiple APIs and want to change the order position of the display
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	Configured during advanced feature authentication
hidden	Configure to true to hide in the document

The configuration in SpringMvc is as follows:

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

}

ApiOperation标记

The definition of each url resource of ApiOperation, the usage method:

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

Used side by side with methods in Controller.
Property configuration:

property name	Remark
value	url's path value
tags	If this value is set, the value of value will be overwritten
description	description of the api resource
basePath	The base path can not be configured
position	If you configure multiple APIs and want to change the order position of the display
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	Configured during advanced feature authentication
hidden	Configure to true to hide in the document
response	the returned object
responseContainer	These objects are valid "List", "Set" or "Map"., others are invalid
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");
    }
  }

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)

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("");
  }

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("");
  }

ResponseHeader

响应头设置，使用方法
@ResponseHeader(name="head1",description="response head conf")

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

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

在SpringMvc中的配置如下：

@ApiModel(description = "群组")