Swagger 注解使用
1. Swagger注解的作用域
API | 作用范围 | 使用位置 |
---|---|---|
@Api | 协议集描述 | 用于controller类上 |
@ApiOperation | 协议描述 | 用在controller的方法上 |
@ApiImplicitParams | 非对象参数集 | 用在controller的方法上 |
@ApiImplicitParam | 非对象参数描述 | 用在@ApiImplicitParams的方法里边 |
@ApiResponses | Response集 | 用在controller的方法上 |
@ApiResponse | Response | 用在 @ApiResponses里边 |
@ApiModel | 描述返回对象的意义 | 用在返回对象类上 |
@ApiModelProperty | 对象属性 | 用在出入参数对象的字段上 |
@ApiParam | 协议描述 | 用在方法、参数、类的字段上 |
2. @Api
使用位置即用在类上,对请求类进行描述。标识一个Controller类是Swagger文档类。
2.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 描述,无实际意义。 |
tags | String[] | "" | 分组 |
basePath | String | "" | 基本路径 |
protocols | String | int | 请求协议 |
authorizations | Authorization[] | @Authorization(value = "") | 高级特性认证时的配置 |
hidden | boolean | false | 是否隐藏(不显示,默认为false) |
2.2 属性value、tags二者的区别
value属性作用在类和作用在方法上都用于描述;
tags属性作用在类和作用在方法上都用于分组,但分组的效果区别很大:
tags作用在类上时,会对全局的方法分组,即根据tags属性值复制多份,此时方法上的tags值无效,方法上tags配或不配效果都一样。
tags作用在方法上时,会根据当前类的所有方法的tags值做分组,粒度更细。
2.3 使用方法
注意:java和scala在@Api注解上使用的区别*java
@Api(tags = "Swagger测试相关接口")
@RestController
*scala
@Api(tags = Array("Swagger测试相关接口"))
@RestController
3. @ApiOperation
用在方法上,对请求方法进行描述。
3.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 描述 |
notes | String | "" | 详细描述 |
tags | String[] | "" | 分组 |
response | Class<?> | Void.class | 响应参数类型 |
responseReference | String[] | "" | 指定对响应类型的引用,本地/远程引用,并将覆盖任何其它指定的response()类 |
httpMethod | String | "" | http请求方式,如:GET、HEAD、POST、PUT、DELETE、OPTION、SPATCH |
hidden | boolean | false | 是否隐藏(不显示)默认为false |
code | int | 200 | http的状态码 |
extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = "", value = "") | 扩展属性 |
3.2 使用方法
@GetMapping("test1")
@ApiOperation(value = "test1接口",notes = "test1接口详细描述")
public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
return ApiUtil.success("success");
}
4. @ApiImplicitParams
常用在方法上,对请求参数列表进行描述。 其中的value属性可包含多个@ApiImplicitParam,对每个参加进行具体的描述。
4.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 描述 |
5. @ApiImplicitParams
用在方法上,对请求参数进行描述。当需要对多个参数进行描述时,作为@ApiImplicitParams的属性使用。
5.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 描述 |
name | String | "" | 参数说明 |
defaultValue | String | "" | 默认值 |
allowableValues | String | "" | 参数允许值 |
required | boolean | false | 是否必填,默认false |
access | String | "" | 参数过滤 |
allowMultiple | boolean | false | 参数是否可以通过多次出现来接受多个值,默认不允许 |
dataType | String | "" | 参数的数据类型,可以使类名或原始数据类型 |
dataTypeClass | Class<?> | Void.class | 参数的数据类型,如果提供则覆盖 dataType |
paramType | String | "" | 参数类型,有效值为 path, query, body, header, form |
example | String | "" | 非body类型的参数示例 |
examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | body类型的参数示例 |
type | String | "" | 添加覆盖检测到的类型的功能 |
format | String | "" | 添加提供自定义format格式的功能 |
readOnly | boolean | false | 添加被指定为只读的功能 |
5.2 使用方法
@GetMapping("test1")
@ApiOperation(value = "test1接口",notes = "test1接口详细描述")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "aa",value = "aa的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
@ApiImplicitParam(name = "bb",value = "bb的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
@ApiImplicitParam(name = "cc",value = "cc的说明",defaultValue = "2",allowableValues = "1,2,3",required = true),
})
6. @ApiParam
用在方法、参数、类的字段上,对请求参数进行描述。
6.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 描述 |
name | String | "" | 参数说明 |
defaultValue | String | "" | 默认值 |
allowableValues | String | "" | 参数允许值 |
required | boolean | false | 是否必填,默认false |
access | String | "" | 参数过滤 |
allowMultiple | boolean | false | 参数是否可以通过多次出现来接受多个值,默认不允许 |
dataType | String | "" | 参数的数据类型,可以使类名或原始数据类型 |
dataTypeClass | Class<?> | Void.class | 参数的数据类型,如果提供则覆盖 dataType |
paramType | String | "" | 参数类型,有效值为 path, query, body, header, form |
example | String | "" | 非body类型的参数示例 |
examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | body类型的参数示例 |
type | String | "" | 添加覆盖检测到的类型的功能 |
format | String | "" | 添加提供自定义format格式的功能 |
readOnly | boolean | false | 添加被指定为只读的功能 |
6.2 使用方法
@GetMapping("test2")
@ApiOperation(value = "test2接口",notes = "test2接口详细描述")
public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
return ApiUtil.success(new TestRes());
}
7. @ApiModel
用在类上,对请求、响应类,实体类进行描述。
7.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 为提供模型的替代名称,默认情况下,使用类名 |
description | String | "" | 类的描述 |
parent | Class<?> parent | Void.class | 为模型提供父类以允许描述继承关系 |
discriminatory | String | "" | 支持模型继承和多态,使用鉴别器的字段的名称,可以断言需要使用哪个子类型 |
subTypes | boolean | false | 是否必填,默认false |
access | Class<?> parent | Void.class | 从此模型继承的子类型数组 |
reference | boolean | false | 指定对应类型定义的引用,覆盖指定的任何其他元数据 |
8 @ApiModelProperty
用在类上,对请求、响应类,实体类进行描述。
8.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | String | "" | 属性说明 |
name | String | "" | 覆盖属性的名称 |
allowableValues | String | "" | 参数允许值 |
access | String | "" | 过滤属性 |
required | boolean | false | 是否必填,默认false |
dataType | String | "" | 参数的数据类型,可以使类名或原始数据类型 |
hidden | boolean | false | 是否隐藏 |
readOnly | String | "" | 添加被指定为只读的功能 |
reference | String | "" | 指定对应类型定义的引用,覆盖指定的任何其他元数据 |
allowEmptyValue | boolean | false | 允许传空值 |
example | String | "" | 属性的示例值 |
8.2 使用方法
注意:java和scala在@ApiModelProperty注解上的使用的区别*java实体类
@Data
@ApiModel(description = "测试请求类")
public class TestReq {
@ApiModelProperty(value = "用户ID",required = true)
private Long userId;
@ApiModelProperty(value = "用户名",example = "张三")
}
*scala实体类
@Data
@ApiModel(description = "测试响应类")
public class TestRes {
@(ApiModelProperty @field)("用户ID")
private Long userId;
@(ApiModelProperty @field)("用户名")
}
9. @ApiResponses
用在方法、类上,对响应状态码列表进行描述。
9.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
value | ApiResponse[] | "" | 响应状态码列表的描述 |
10. @ApiResponse
用在方法上,对响应状态码进行描述。一般作为@ApiResponses的属性使用。
10.1 注解的属性
属性名称 | 属性类型 | 属性默认值 | 属性描述 |
---|---|---|---|
code | int | "" | 响应的HTTP状态码 |
message | String | "" | 响应的描述 |
response | Class<?> | Void.class | 用于描述消息有效负载的可选响应类,对应于响应消息对象的 schema 字段 |
reference | String | "" | 指定对响应类型的引用,指定的应用可以使本地引用,也可以是远程引用,将按原样使用,并将覆盖任何指定的response()类 |
responseHeaders | ResponseHeader[] | @ResponseHeader(name = "", response = Void.class) | 可能响应的header列表 |
responseContainer | String | "" | 声明响应的容器,有效值为List,Set,Map,任何其他值都将被忽略 |
10.2 使用方法
@GetMapping("test2")
@ApiOperation(value = "test2接口",notes = "test2接口详细描述")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "请求成功", responseHeaders = {@ResponseHeader(name = "header1", description = "header1的描述",response = String.class)}),
@ApiResponse(code = 401, message = "没有权限"),
@ApiResponse(code = 403, message = "禁止访问")
})
public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
return ApiUtil.success(new TestRes());
}