Knife4j 注解详谈
Posted liuyangfirst
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Knife4j 注解详谈相关的知识,希望对你有一定的参考价值。
Controller层添加注解
@Api:用于类;表示标识这个类是swagger的资源
属性名称 | 数据类型 | 默认值 | 说明 |
value | String | "" | 字段说明 |
tags | String[] | "" | 标签说明 |
description | String | "" | 详情描述 |
basePath |
String | "" | 基本路径可以不配置 |
position | int | "" | 如果配置多个Api 想改变显示的顺序位置 |
produces | String | "" | 提供者 (For example, "application/json, application/xml") |
consumes | String | "" | 消费者(For example, "application/json, application/xml") |
protocols | String | "" | 协议(Possible values: http, https, ws, wss.) |
authorizations | Authorization[] | "" | 高级特性认证时配置 |
hidden | boolean | "" | 配置为true 将在文档中隐藏 |
使用实例:
注解加载在controller类上
常用模型:
1 @Api(tags = "HELLO CONTROLLER 测试功能接口") 2 @RestController 3 public class HelloController { 4 5 }
@ApiResponses:在 Rest 接口上使用,用作返回值的描述
参数
属性名称 | 数据类型 | 默认值 | 说明 |
value | ApiResponse[] | "" | 访问对象 |
ApiResponse参数
属性名称 | 数据类型 | 默认值 | 说明 |
code | String | "" | 响应的HTTP状态码 |
message | String | "" | 响应的信息内容 |
response | Class<?> | "" | 用于描述消息有效负载的可选响应类,对应于响应消息对象的 schema 字段 |
reference | String | "" | 指定对响应类型的引用,指定的应用可以使本地引用,也可以是远程引用,将按原样使用,并将覆盖任何指定的response()类 |
responseHeaders | ResponseHeader[] | "" | 声明包装响应的容器,有效值为List或Set,任何其他值都将被覆盖 |
responseContainer | String | "" | 声明响应的容器,有效值为List,Set,Map,任何其他值都将被忽略 |
examples | Example | "" | 例子 |
使用实例:
注解加载在字段上
常用模型:
1 @ApiResponses(value = { 2 @ApiResponse(code = 200, message = "接口返回成功状态"), 3 @ApiResponse(code = 500, message = "接口返回未知错误,请联系开发人员调试") 4 }) 5 @PostMapping("hello") 6 public Results<UserVO> hello(@RequestBody UserVO userVO){ 7 8 Results<UserVO> results = new Results<>(200,"SUCCESS", userVO); 9 return results; 10 }
@ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义
参数
属性名称 | 数据类型 | 默认值 | 说明 |
value | String | "" | url的路径值 |
notes | String | "" | 文本说明 |
tags | String[] | "" | 如果设置这个值、value的值会被覆盖 |
response | Class<?> | "" | 返回的对象 |
responseContainer | String | "" | 声明响应的容器,有效值为List,Set,Map,任何其他值都将被忽略 |
responseReference | String | "" | 声明包装响应的容器,有效值为List或Set,任何其他值都将被覆盖 |
httpMethod | String | "" | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" |
position | int | "" | 如果配置多个Api 想改变显示的顺序位置 |
nickname | String | "" | 昵称 |
produces | String | "" | 提供者 (For example, "application/json, application/xml") |
consumes | String | "" | 消费者(For example, "application/json, application/xml") |
protocols | String | "" | 协议(Possible values: http, https, ws, wss.) |
authorizations | Authorization[] | "" | 高级特性认证时配置 |
hidden | boolean | "" | 隐藏 |
responseHeaders | ResponseHeader[] | "" | 声明包装响应的容器,有效值为List或Set,任何其他值都将被覆盖 |
code | String | "" | http的状态码 默认 200 |
extensions | Extension[] | "" | 扩展属性 |
ignoreJsonView | boolean | "" | 是否忽略显示 |
使用实例:
注解加载在字段上
常用模型:
1 @ApiOperation(value = "Hello 测试接口", notes = "访问此接口,返回hello语句,测试接口") 2 @PostMapping("hello") 3 public Results<UserVO> hello(@RequestBody UserVO userVO){ 4 5 Results<UserVO> results = new Results<>(200,"SUCCESS", userVO); 6 return results; 7 }
@PathVariable:是获取get方式,url后面参数,进行参数绑定(单个参数或两个以内参数使用)
参数
属性名称 | 数据类型 | 默认值 | 说明 |
value | String | "" | url的路径值 |
name | String | "" | 重写属性名字 |
required | String | "" | 是否必填 |
使用实例:
注解加载在字段上
常用模型:
1 @ApiResponses(value = { 2 @ApiResponse(code = 200, message = "接口返回成功状态"), 3 @ApiResponse(code = 500, message = "接口返回未知错误,请联系开发人员调试") 4 }) 5 @ApiOperation(value = "获取用户信息", notes = "访问此接口,返回用户信息") 6 @PostMapping("/getUser/{id}") 7 public String getUser(@PathVariable String id) throws InterruptedException { 8 // 业务... 9 return ""; 10 }
@RequestBody :在当前对象获取整个http请求的body里面的所有数据(两个以上参数封装成对象使用)
参数
属性名称 | 数据类型 | 默认值 | 说明 |
required | String | "" | 是否必填 |
使用实例:
注解加载在传入参数对象上
常用模型:
1 @ApiResponses(value = { 2 @ApiResponse(code = 200, message = "接口返回成功状态"), 3 @ApiResponse(code = 500, message = "接口返回未知错误,请联系开发人员调试") 4 }) 5 @ApiOperation(value = "Hello 测试接口", notes = "访问此接口,返回hello语句,测试接口") 6 @PostMapping("hello") 7 public Results<UserVO> hello(@RequestBody UserVO userVO){ 8 Results<UserVO> results = new Results<>(200,"SUCCESS", userVO); 9 return results; 10 }
以上是关于Knife4j 注解详谈的主要内容,如果未能解决你的问题,请参考以下文章
Knife4j解决SpringBoot整合Knife4j 3.0.3 文件上传不显示文件域
Knife4j解决SpringBoot整合Knife4j 3.0.3 文件上传不显示文件域
Springboot整合springfox3+knife4j,生成接口文档