Article Directory
Write in front
As a front-end and back-end tool, swagger, as a back-end developer, must pay attention to several points.
- 1. When writing an entity class, you must pay attention to the completeness of the entity, such as specifying the position and example. This is a very good habit
- 2. When writing the controller layer, pay attention to the difference between get and post. Already parameters are on the path or as request parameters or method bodies or forms, which are different for swagger2. It is recommended to distinguish well. If the parameter is on the path or as a request parameter, bring an example at the end to illustrate the function and demo of this parameter
- 3. A well-written swagger is bound to take a lot of time, but this time can make the front and back ends less communication. After all, code writers like to write code quietly. These messy communications, let swagger.
One, Swagger annotation
| Scope of action | API | utilized location |
|---|---|---|
| Protocol set description | @Api | Used on the controller class |
| Protocol description | @ApiOperation | Used in the controller method |
| Non-object parameter set | @ApiImplicitParams | Used in the controller method |
| Non-object parameter description | @ApiImplicitParam | Used in the @ApiImplicitParams method |
| Object parameter description | @ApiParam | Used in the @ApiImplicitParams method to define the received parameter form |
| Describe the meaning of the returned object | @ApiModel | Used in the return object class |
| Object attributes | @ApiModelProperty | Used on the field of the parameter object |
| Response集 | @ApiResponses | Used in the controller method |
| Response | @ApiResponse | Used in @ApiResponses |
| Response | @ResponseHeader | ~ |
Two, swagger2 annotation of entity entity class
2.1 @ApiModel
Used on the response class, it represents a message that returns the response data
(this is generally used in scenarios such as @RequestBody when the post is created, when the request parameters cannot
be described using the @ApiImplicitParam annotation)
Based on
@ApiModel (value = "User entity class", description = "Description User User field")
2.2 @ApiModelProperty
Used in attributes to describe the attributes of the response class
On the field (note that position must be added, otherwise there may be garbled json parsing)
@ApiModelProperty(value = "update time", position = 16, example = "2020-01-01 00:00:00")
Three, the swagger2 annotation of the Controller
3.1 @Api
Based on
@Api (tags = "user object", description = "registered user, the user object CRUD")
3.2 @ApiOperation
Method
@ApiOperation("Add User")
3.3 @ApiImplicitParams
@ApiImplicitParams: Used in the request method to indicate a set of parameter descriptions
@ApiImplicitParam: Used in the @ApiImplicitParams annotation to specify all aspects of a request parameter
name: parameter name
value: Chinese character description and explanation of the
parameter required: whether the parameter must be passed
paramType: Where to put the parameter
· header --> get request parameter: @RequestHeader
· query --> get request parameter: @RequestParam
· path (for restful interface) --> get request parameter: @PathVariable
· body (Not commonly used)
· form (not commonly used)
dataType: parameter type, default String, other values dataType="Integer"
defaultValue: default value of the parameter
Note: To distinguish query common parameters, both? Splicing path. The parameters on the path are obtained from the context. body method body, set parameters on the method body
