Common swagger2 annotations and swagger2 annotations

Common swagger2 annotations and swagger2 annotations
Commonly used annotations include:

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

1. api tag

The Api is used on the class to describe the role of the class. You can mark a Controller class as a swagger document resource. Usage:

@Api(value = "/user", description = "Operations about user")

Used in parallel with the Controller annotation. Property Configuration:

Attribute name	Remarks
Value	Url path value
Tags	If this value or value is set, it will be overwritten.
Description	Description of api Resources
BasePath	The basic path does not need to be configured.
Position	If you want to change the display sequence for multiple APIs
Produces	For example, "application/json, application/xml"
Consumes	For example, "application/json, application/xml"
Protocols	Possible values: http, https, ws, wss.
Authorizations	Advanced feature authentication Configuration
Hidden	If it is set to true, it will be hidden 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 {}

2. ApiOperation mark

ApiOperation: Used in methods, describes the role of the method, the definition of each url resource, usage:

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

It is used in parallel with the method in Controller.
Property Configuration:

Attribute name	Remarks
Value	Url path value
Tags	If this value or value is set, it will be overwritten.
Description	Description of api Resources
BasePath	The basic path does not need to be configured.
Position	If you want to change the display sequence for multiple APIs
Produces	For example, "application/json, application/xml"
Consumes	For example, "application/json, application/xml"
Protocols	Possible values: http, https, ws, wss.
Authorizations	Advanced feature authentication Configuration
Hidden	If it is set to true, it will be hidden in the document.
Response	Returned object
ResponseContainer	These objects are valid "List", "Set" or "Map". Other objects are invalid.
HttpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
Code	Http Status Code 200 by default
Extensions	Extended attributes

The configuration in SpringMvc is as follows:

@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 flag

ApiParam request attributes. Usage:

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

It is used in parallel with the method in Controller.

Property Configuration:

Attribute name	Remarks
Name	Attribute name
Value	Attribute Value
DefaultValue	Default Attribute Value
AllowableValues	Optional
Required	Required or not
Access	But many descriptions
AllowMultiple	The default value is false.
Hidden	Hide this property
Example	Example

The configuration in SpringMvc is as follows:

 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: Response configuration. Usage:

@ApiResponse(code = 400, message = "Invalid user supplied")

It is used in parallel with the method in Controller. Property Configuration:

Attribute name	Remarks
Code	Http status code
Message	Description
Response	Default response class Void
Reference	Refer to configuration in ApiOperation
ResponseHeaders	Refer to ResponseHeader attribute configuration instructions
ResponseContainer	Refer to configuration in ApiOperation

The configuration in SpringMvc is as follows:

 @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: Response set configuration. Usage:

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

It is used in parallel with the method in Controller. Property Configuration:

Attribute name	Remarks
Value	Multiple ApiResponse configurations

The configuration in SpringMvc is as follows:

 @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

Response Header settings, usage

@ResponseHeader(name="head1",description="response head conf")

It is used in parallel with the method in Controller. Property Configuration:

Attribute name	Remarks
Name	Response Header name
Description	Header description
Response	Default response class Void
ResponseContainer	Refer to configuration in ApiOperation

The configuration in SpringMvc is as follows:

@ ApiModel (description = "group ")

7. Others

• @ ApiImplicitParams: contains a set of parameter descriptions on the method;
• @ ApiImplicitParam: Used in the @ ApiImplicitParams annotation to specify all aspects of a request parameter
  • ParamType: where the parameter is stored
  • Name: Meaning of the Parameter
  • Value: Parameter Name
  • DataType: The parameter type, which can be String or int. It is useless.
  • Required: required
  • DefaultValue: Default Value of the Parameter
• @ ApiResponses: indicates a group of responses;
• @ ApiResponse: Used in @ ApiResponses. It is generally used to express an error response message;
  • Code: Response code (int type), customizable
  • Message: response information corresponding to the status code
• @ ApiModel: Describe the information of a Model (this is generally used when post is created, in scenarios such as @ RequestBody, when the request parameter cannot be described using the @ ApiImplicitParam annotation;
• @ ApiModelProperty: Describes the attributes of a model.

Reprinted from
Author: Xiangdong_She
Link: http://www.jianshu.com/p/12f4394462d5
Source: Simplified book