Swagger Note API Detail description

The commonly used annotations are:

• Api
• Apimodel
• Apimodelproperty
• Apioperation
• Apiparam
• Apiresponse
• Apiresponses
• Responseheader

1. API tags

The API is used on classes to illustrate the role of the class. You can tag a controller class as a Swagger document resource, using the following method:

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

Used in parallel with controller annotations. Property configuration:

Property name	Notes
Value	Path value of the URL
Tags	If this value is set, value is overwritten
Description	Description of the API resource
BasePath	Basic path can not be configured
Position	If you configure multiple APIs to change the order 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	Advanced feature authentication when configured
Hidden	Configured to True to 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 the method, explains the function of the method, each URL resource definition, use way:

@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 in parallel with the method in the controller.
Property configuration:

Property name	Notes
Value	Path value of the URL
Tags	If this value is set, value is overwritten
Description	Description of the API resource
BasePath	Basic path can not be configured
Position	If you configure multiple APIs to change the order 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	Advanced feature authentication when configured
Hidden	Configured to True to be hidden in the document
Response	The returned object
Responsecontainer	These objects are valid "List", "Set" or "Map"., Other invalid
HttpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "Options" and "PATCH"
Code	HTTP status Code default 200
Extensions	Extended Properties

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 would 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 Mark

Apiparam request properties, how to use:

"Created user object", required = true)  User user)

Used in parallel with the method in the controller.

Property configuration:

Property name	Notes
Name	Property name
Value	Property value
DefaultValue	Default Property value
Allowablevalues	Can not be configured
Required	Whether the attribute is required
Access	But more descriptive.
AllowMultiple	Default is False
Hidden	Hide this property
Example	Example Child

The configuration in SPRINGMVC is as follows:

 public ResponseEntity<Order> getOrderById(      "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)      @PathVariable("orderId") String orderId)

4. Apiresponse

Apiresponse: Response configuration, how to use:

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

Used in parallel with the method in the controller. Property configuration:

Property name	Notes
Code	Status code for HTTP
Message	Describe
Response	Default Response Class Void
Reference	Configuration in the reference apioperation
Responseheaders	Reference Responseheader Property Configuration instructions
Responsecontainer	Configuration in the reference 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, how to use:

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

Used in parallel with the method in the controller. Property configuration:

Property name	Notes
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, how to use

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

Used in parallel with the method in the controller. Property configuration:

Property name	Notes
Name	Response header Name
Description	Header description
Response	Default Response Class Void
Responsecontainer	Configuration in the reference apioperation

The configuration in SPRINGMVC is as follows:

@ApiModel(description = "群组")

7. Other

• @ApiImplicitParams: Use the method to include a set of parameter descriptions;
• @ApiImplicitParam: Use in @apiimplicitparams Annotations to specify aspects of a request parameter
  • Paramtype: Where to put the parameters
  • Name: The meaning of the parameter representation
  • Value: Parameter name
  • DataType: Parameter type, string/int, useless
  • Required: Is it necessary
  • DefaultValue: Default values for parameters
• @ApiResponses: Used to represent a set of responses;
• @ApiResponse: Used in @apiresponses, generally used to express a wrong response information;
  • Code: Response Code (int type), customizable
  • Message: Response information corresponding to the status code
• @ApiModel: Describes a model of the information (this is generally used when the post is created, using a scene such as @requestbody, request parameters can not be described using @apiimplicitparam annotations;
• @ApiModelProperty: Describes the properties of a model.

Xiangdong_she
Links: Https://www.jianshu.com/p/12f4394462d5
Source: Pinterest
Copyright belongs to the author. Commercial reprint please contact the author for authorization, non-commercial reprint please specify the source.

Swagger Note API Detail description