swagger framework

swagger framework

---

Introduction

Swagger is one of the most popular API management tools in the world. At present, Swagger has formed an ecosystem that can manage the entire life cycle of APIs, from design, documentation to testing and deployment. Several important features of Swagger:

• Code intrusive annotations
• Follow the YAML document format
• Very suitable for three-terminal (PC, IOS, and Android) API management, especially suitable for the completely separated front-end and back-end architectural models
• Reduce unnecessary documents, in line with the concept of agile development
• Powerful

effect:

• Interface documentation is automatically generated online
• function test

advantage:

1. Greatly reduce front-end and back-end communication
2. Easy to find and test interfaces
3. Improve the development efficiency of the team
4. Make it easier for newcomers to understand the project

---

1. Commonly used annotations

swagger explains the API documentation by declaring annotations in the controller

1. @Api()
   is used on the requested class, indicating the description of the class, and also means that this class is a resource of swagger2.
   Parameters:
   1 .tags: Indicates the function of this class. The parameter is an array and can be filled in more than one.
   2 .value = "This parameter has no meaning, it is not displayed on the UI interface, so no configuration is required"
   3 .description = "Basic user information operation"

2. @ApiOperation():
   Used for a method, indicating an http request to access the operation of the method
   Parameters:
   1. value = "purpose and function of the method"
   2. notes = "notes and remarks of the method"
   3. tags: describe the method The function, the parameter is an array, which can be multiple
   4. Format: tags={"Action 1", "Action 2"}
   5. {It is not recommended to use this parameter here, it will make the interface look messy, the first two commonly used}

3. @ApiModel():
   Used on the response entity class to describe the role of the entity
   Parameters:
   description="Description of the role of the entity"

4. @ApiModelProperty:
   Used on attributes to describe the attributes of the entity class Parameters
   :
   1 .value="username" describes the meaning of the parameter
   2 .name="name" the variable name of the parameter
   3 .required=true Whether the parameter is required

5. @ApiImplictParams:
   used in the request method, including multiple @ApliImplictParam

6. @ApliImplictParam :
   Used for methods, representing individual request parameters
   Parameters:
   1. name="parameter ming"
   2. value="parameter description"
   3. dataType="data type"
   4. paramType="query" indicates where the parameter is placed
   5. Header request parameter acquisition: @RequestHeader
   6 query request parameter acquisition: @RequestParam
   7 path (for restful interface) request parameter acquisition: @PathVariable
   8 body (not commonly used)
   9 form (not commonly used)
   10. defaultValue="the default value of the parameter"
   11. required="true" indicates whether the parameter must be passed

7. @ApiParam():
   Used for methods, parameters, and field descriptions to indicate the requirements and descriptions of parameters
   Parameters:
   name="parameter name"
   value="a brief description of the parameter"
   defaultValue="parameter default value"
   required="true" indicates an attribute Is it required, the default is false

8. @ApiResponses:
   Used in the request method, different responses are indicated according to the response code.
   One @ApiResponses contains multiple @ApiResponse

9. @ApiResponse:
   Used in the request method to indicate different responses
   Parameters:
   code="404" indicates the response code (int type), you can customize
   message="the response information corresponding to the status code"

10. @ApiIgnore():
    Used on classes or methods, not displayed on the page