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 }
View Code

 

@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     }
View Code

 

@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     }
View Code

 

@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     }
View Code

 

@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     }
View Code

 

以上是关于Knife4j 注解详谈的主要内容,如果未能解决你的问题,请参考以下文章

Knife4j添加lombok及注解初探

Knife4j解决SpringBoot整合Knife4j 3.0.3 文件上传不显示文件域

Knife4j解决SpringBoot整合Knife4j 3.0.3 文件上传不显示文件域

Springboot整合springfox3+knife4j,生成接口文档

swagger knife4j 解决接口下载文件响应乱码问题

swagger knife4j 解决接口下载文件响应乱码问题