Swagger Annotation

Use the location to use on the class to describe the request class. Identifies a Controller class is the Swagger document class.

The value attribute is used to describe both the role of the class and the role of the method;

The tags attribute is used for grouping both on classes and methods, but the effect of grouping is very different:

When tags act on a class, the global methods are grouped, that is, multiple copies are made according to the tags attribute value. At this time, the tags value on the method is invalid, and the effect of matching or not matching the tags on the method is the same.

When tags act on a method, they will be grouped according to the tags values ​​of all methods of the current class, with a finer granularity.

Note: The difference between java and scala in @Api annotation

*java
@Api(tags = "Swagger test related interface")
@RestController
*scala
@Api(tags = Array("Swagger test related interface"))
@RestController

Used in methods, to describe the request method.

@GetMapping("test1")
@ApiOperation(value = "test1 interface", notes = "test1 interface detailed description")
public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
        return ApiUtil.success("success");
}

Commonly used in methods to describe the request parameter list. The value attribute can contain multiple @ApiImplicitParam, and describe each participant in detail.

Used in methods to describe request parameters. When multiple parameters need to be described, it is used as a property of @ApiImplicitParams.

@GetMapping("test1")
@ApiOperation(value = "test1 interface", notes = "test1 interface detailed description")
@ApiImplicitParams(value = {
        @ApiImplicitParam(name = "aa",value = "aa description",defaultValue = "1",allowableValues ​​= "1,2,3",required = true),
        @ApiImplicitParam(name = "bb",value = "bb description",defaultValue = "1",allowableValues ​​= "1,2,3",required = true),
        @ApiImplicitParam(name = "cc",value = "Description of cc",defaultValue = "2",allowableValues ​​= "1,2,3",required = true),
})

Used in fields of methods, parameters, and classes to describe request parameters.

@GetMapping("test2")
@ApiOperation(value = "test2 interface", notes = "test2 interface detailed description")
public ApiResult<TestRes> test2(@ApiParam(value = "aa description") @RequestParam String aa, @ApiParam(value = "bb description") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
}

Used in classes to describe requests, response classes, and entity classes.

Used in classes to describe requests, response classes, and entity classes.

Note: The difference between java and scala in the use of @ApiModelProperty annotation

*java entity class
@Data
@ApiModel(description = "Test request class")
public class TestReq {
    @ApiModelProperty(value = "User ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "Username", example = "Zhang San")
}
*scala entity class
@Data
@ApiModel(description = "Test response class")
public class TestRes {
    @(ApiModelProperty @field)("User ID")
    private Long userId;
    @(ApiModelProperty @field)("Username")
}

Used on methods and classes to describe the response status code list.

Used in the method to describe the response status code. Generally used as a property of @ApiResponses.

@GetMapping("test2")
@ApiOperation(value = "test2 interface", notes = "test2 interface detailed description")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Request successful", responseHeaders = {@ResponseHeader(name = "header1", description = "description of header1",response = String.class)}),
        @ApiResponse(code = 401, message = "No permission"),
        @ApiResponse(code = 403, message = "Access forbidden")
})
public ApiResult<TestRes> test2(@ApiParam(value = "aa description") @RequestParam String aa, @ApiParam(value = "bb description") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
}