Skip to main content
版本:1.3.1

Swagger 注解使用

1. Swagger注解的作用域

API作用范围使用位置
@Api协议集描述用于controller类上
@ApiOperation协议描述用在controller的方法上
@ApiImplicitParams非对象参数集用在controller的方法上
@ApiImplicitParam非对象参数描述用在@ApiImplicitParams的方法里边
@ApiResponsesResponse集用在controller的方法上
@ApiResponseResponse用在 @ApiResponses里边
@ApiModel描述返回对象的意义用在返回对象类上
@ApiModelProperty对象属性用在出入参数对象的字段上
@ApiParam协议描述用在方法、参数、类的字段上

2. @Api

使用位置即用在类上,对请求类进行描述。标识一个Controller类是Swagger文档类。

2.1 注解的属性

属性名称属性类型属性默认值属性描述
valueString""描述,无实际意义。
tagsString[]""分组
basePathString""基本路径
protocolsStringint请求协议
authorizationsAuthorization[]@Authorization(value = "")高级特性认证时的配置
hiddenbooleanfalse是否隐藏(不显示,默认为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 注解的属性

属性名称属性类型属性默认值属性描述
valueString""描述
notesString""详细描述
tagsString[]""分组
responseClass<?>Void.class响应参数类型
responseReferenceString[]""指定对响应类型的引用,本地/远程引用,并将覆盖任何其它指定的response()类
httpMethodString""http请求方式,如:GET、HEAD、POST、PUT、DELETE、OPTION、SPATCH
hiddenbooleanfalse是否隐藏(不显示)默认为false
codeint200http的状态码
extensionsExtension[]@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 注解的属性

属性名称属性类型属性默认值属性描述
valueString""描述

5. @ApiImplicitParams

用在方法上,对请求参数进行描述。当需要对多个参数进行描述时,作为@ApiImplicitParams的属性使用。

5.1 注解的属性

属性名称属性类型属性默认值属性描述
valueString""描述
nameString""参数说明
defaultValueString""默认值
allowableValuesString""参数允许值
requiredbooleanfalse是否必填,默认false
accessString""参数过滤
allowMultiplebooleanfalse参数是否可以通过多次出现来接受多个值,默认不允许
dataTypeString""参数的数据类型,可以使类名或原始数据类型
dataTypeClassClass<?>Void.class参数的数据类型,如果提供则覆盖 dataType
paramTypeString""参数类型,有效值为 path, query, body, header, form
exampleString""非body类型的参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))body类型的参数示例
typeString""添加覆盖检测到的类型的功能
formatString""添加提供自定义format格式的功能
readOnlybooleanfalse添加被指定为只读的功能

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 注解的属性

属性名称属性类型属性默认值属性描述
valueString""描述
nameString""参数说明
defaultValueString""默认值
allowableValuesString""参数允许值
requiredbooleanfalse是否必填,默认false
accessString""参数过滤
allowMultiplebooleanfalse参数是否可以通过多次出现来接受多个值,默认不允许
dataTypeString""参数的数据类型,可以使类名或原始数据类型
dataTypeClassClass<?>Void.class参数的数据类型,如果提供则覆盖 dataType
paramTypeString""参数类型,有效值为 path, query, body, header, form
exampleString""非body类型的参数示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))body类型的参数示例
typeString""添加覆盖检测到的类型的功能
formatString""添加提供自定义format格式的功能
readOnlybooleanfalse添加被指定为只读的功能

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 注解的属性

属性名称属性类型属性默认值属性描述
valueString""为提供模型的替代名称,默认情况下,使用类名
descriptionString""类的描述
parentClass<?> parentVoid.class为模型提供父类以允许描述继承关系
discriminatoryString""支持模型继承和多态,使用鉴别器的字段的名称,可以断言需要使用哪个子类型
subTypesbooleanfalse是否必填,默认false
accessClass<?> parentVoid.class从此模型继承的子类型数组
referencebooleanfalse指定对应类型定义的引用,覆盖指定的任何其他元数据

8 @ApiModelProperty

用在类上,对请求、响应类,实体类进行描述。

8.1 注解的属性

属性名称属性类型属性默认值属性描述
valueString""属性说明
nameString""覆盖属性的名称
allowableValuesString""参数允许值
accessString""过滤属性
requiredbooleanfalse是否必填,默认false
dataTypeString""参数的数据类型,可以使类名或原始数据类型
hiddenbooleanfalse是否隐藏
readOnlyString""添加被指定为只读的功能
referenceString""指定对应类型定义的引用,覆盖指定的任何其他元数据
allowEmptyValuebooleanfalse允许传空值
exampleString""属性的示例值

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 注解的属性

属性名称属性类型属性默认值属性描述
valueApiResponse[]""响应状态码列表的描述

10. @ApiResponse

用在方法上,对响应状态码进行描述。一般作为@ApiResponses的属性使用。

10.1 注解的属性

属性名称属性类型属性默认值属性描述
codeint""响应的HTTP状态码
messageString""响应的描述
responseClass<?>Void.class用于描述消息有效负载的可选响应类,对应于响应消息对象的 schema 字段
referenceString""指定对响应类型的引用,指定的应用可以使本地引用,也可以是远程引用,将按原样使用,并将覆盖任何指定的response()类
responseHeadersResponseHeader[]@ResponseHeader(name = "", response = Void.class)可能响应的header列表
responseContainerString""声明响应的容器,有效值为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());
}