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