Swwager Annotation Instructions
1. Scope of swwager annotations
API | Scope | Where to use |
---|---|---|
@Api | Protocol set description | Used on the controller class |
@ApiOperation | Protocol description | Used in controller methods |
@ApiImplicitParams | Non-object parameter set | Used in controller methods |
@ApiImplicitParam | Non-object parameter description | Used in methods of @ApiImplicitParams |
@ApiResponses | Response set | Used in the controller's method |
@ApiResponse | Response | Used in @ApiResponses |
@ApiModel | Describe the meaning of the returned object | Used in the returned object class |
@ApiModelProperty | Object property | Used on the fields of the parameter object |
@ApiParam | Protocol description | Used on methods, parameters, fields of classes |
2. @Api
Use the location to use on the class to describe the request class. Identifies a Controller class is the Swagger document class.
2.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | Description, meaningless. |
tags | String[] | "" | Grouping |
basePath | String | "" | Base Path |
protocols | String | int | Request Protocol |
authorizations | Authorization[] | @Authorization(value = "") | Configuration for advanced feature authentication |
hidden | boolean | false | Is it hidden (not displayed, the default is false) |
2.2 The difference between attribute value and tags
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.
2.3 How to use
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
3. @ApiOperation
Used in methods, to describe the request method.
3.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | Description |
notes | String | "" | Detailed description |
tags | String[] | "" | Grouping |
response | Class<?> | Void.class | Response parameter type |
responseReference | String[] | "" | Specifies a reference to the response type, local/remote reference, and will override any other specified response() class |
httpMethod | String | "" | http request method, such as: GET, HEAD, POST, PUT, DELETE, OPTION, SPATCH |
hidden | boolean | false | whether hidden (not displayed) defaults to false |
code | int | 200 | http status code |
extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = "", value = "") | Extension Properties |
3.2 How to use
@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");
}
4. @ApiImplicitParams
Commonly used in methods to describe the request parameter list. The value attribute can contain multiple @ApiImplicitParam, and describe each participant in detail.
4.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | Description |
5. @ApiImplicitParams
Used in methods to describe request parameters. When multiple parameters need to be described, it is used as a property of @ApiImplicitParams.
5.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | Description |
name | String | "" | Parameter Description |
defaultValue | String | "" | default value |
allowableValues | String | "" | Parameter allowable values |
required | boolean | false | Required, default false |
access | String | "" | Parameter Filter |
allowMultiple | boolean | false | Whether the parameter can accept multiple values by appearing multiple times, the default is not allowed |
dataType | String | "" | The data type of the parameter, which can be a class name or a primitive data type |
dataTypeClass | Class<?> | Void.class | The data type of the parameter, overriding dataType |
paramType | String | "" | Parameter type, valid values are path, query, body, header, form |
example | String | "" | Parameter example of non-body type |
examples | Example | @Example(value = @ExampleProperty(mediaType = "", value = "")) | Parameter example of body type |
type | String | "" | Add functionality to override detected types |
format | String | "" | Add the function to provide custom format format |
readOnly | boolean | false | Adds features designated as read-only |
5.2 How to use
@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),
})
6. @ApiParam
Used in fields of methods, parameters, and classes to describe request parameters.
6.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | Description |
name | String | "" | Parameter Description |
defaultValue | String | "" | default value |
allowableValues | String | "" | Parameter allowable values |
required | boolean | false | Required, default false |
access | String | "" | Parameter Filter |
allowMultiple | boolean | false | Whether the parameter can accept multiple values by appearing multiple times, the default is not allowed |
dataType | String | "" | The data type of the parameter, which can be a class name or a primitive data type |
dataTypeClass | Class<?> | Void.class | The data type of the parameter, overriding dataType |
paramType | String | "" | Parameter type, valid values are path, query, body, header, form |
example | String | "" | Parameter example of non-body type |
examples | Example | @Example(value = @ExampleProperty(mediaType = "", value = "")) | Parameter example of body type |
type | String | "" | Add functionality to override detected types |
format | String | "" | Add the function to provide custom format format |
readOnly | boolean | false | Adds features designated as read-only |
6.2 How to use
@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());
}
7. @ApiModel
Used in classes to describe requests, response classes, and entity classes.
7.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | is an alternative name to provide the model, by default, the class name is used |
description | String | "" | Class description |
parent | Class<?> parent | Void.class | Provides a parent class for the model to allow describing inheritance relationships |
discriminatory | String | "" | Supports model inheritance and polymorphism, using the name of the discriminator's field, you can assert which subtype to use |
subTypes | boolean | false | Required, default false |
access | Class<?> parent | Void.class | Array of subtypes inherited from this model |
reference | boolean | false | Specifies a reference to the corresponding type definition, overriding any other metadata specified |
8 @ApiModelProperty
Used in classes to describe requests, response classes, and entity classes.
8.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | String | "" | Attribute Description |
name | String | "" | Override property name |
allowableValues | String | "" | Parameter allowable values |
access | String | "" | Filter Attribute |
required | boolean | false | Required, default false |
dataType | String | "" | The data type of the parameter, which can be a class name or a primitive data type |
hidden | boolean | false | Hidden |
readOnly | String | "" | Add functionality designated as read-only |
reference | String | "" | Specifies a reference to the corresponding type definition, overriding any other metadata specified |
allowEmptyValue | boolean | false | Allow empty values |
example | String | "" | Example value for attribute |
8.2 How to use
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")
}
9. @ApiResponses
Used on methods and classes to describe the response status code list.
9.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
value | ApiResponse[] | "" | Description of response status code list |
10. @ApiResponse
Used in the method to describe the response status code. Generally used as a property of @ApiResponses.
10.1 Attributes of annotations
Property Name | Property Type | Property Default Value | Property Description |
---|---|---|---|
code | int | "" | Response HTTP Status Code |
message | String | "" | Description of the response |
response | Class<?> | Void.class | An optional response class used to describe the message payload, corresponding to the schema field of the response message object |
reference | String | "" | Specifies a reference to the response type, the specified application can make a local reference, or a remote reference, will be used as is, and will override any specified response() class |
responseHeaders | ResponseHeader[] | @ResponseHeader(name = "", response = Void.class) | List of possible response headers |
responseContainer | String | "" | Declare the container of the response, valid values are List, Set, Map, any other value will be ignored |
10.2 How to use
@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());
}