相关文章推荐
小百科  ›  Swagger 注解使用 | Apache Linkis
宽容的山楂
7 月前
Skip to main content

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());
}

Linkis
社区
订阅邮件组

Apache Linkis is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

 
推荐文章
今天看啥   ·   Py中国   ·   codingpro   ·   小百科   ·   link之家   ·   卧龙AI搜索
删除内容请联系邮箱 2879853325@qq.com
小百科 - 百科知识指南
© 2024 ~ 沪ICP备11025650号