SpringBoot集成Swagger2的增强版Knife4j

1. 背景

作为SpringBoot集成中间件其中的一篇文章吧，既然打算出这么一个系列了，争取做到虽小却全，又精又美的一个系列吧。

Swagger应该都有接触吧，knife4j是Swagger2的增强版，更加友好的操作页面，更多强大的功能，基于Swagger2和 OpenAPI，提供了一个更好的接口文档界面，本文主要演示了如何使用SpringBoot集成Knife4j。

本文拆分自笑小枫-SpringBoot系列 ， 更为精简的介绍了SpringBoot如何集成中间件。如果想系统的使用SpringBoot，可以参考笑小枫-SpringBoot系列

  • Spring Boot版本: 2.7.12
  • Knife4j版本: 4.4.0

2. 配置后端接口

2.1 什么是knife4j😴

先贴官网Knife4j

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案。

增强扩展

  • 基础ui组件(自定义文档、动态参数调试、I18n、接口排序、导出等)
  • 基于Springfox框架+Swagger2规范的自动注入starter
  • 基于Springdoc-openapi+OAS3规范的自动注入starter
  • 提供对主流网关组件的统一聚合OpenAPI接口文档的解决方案

2.2 怎么使用knife4j🎨

版本选择

关于版本，可以前往官网查看 Knife4j版本参考

Spring Boot 3

  • Spring Boot 3 只支持OpenAPI3规范
  • Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
  • JDK版本必须 >= 17

Spring Boot 2

  • Spring Boot 版本建议 2.4.0~3.0.0之间
  • Spring Boot 版本 < 2.4 版本则建议选择Knife4j 4.0之前的版本

👉第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：👇

        <!-- 引入knife4j依赖 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

👉第二步：创建Swagger配置依赖，代码如下：👇

package com.maple.knife4j.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;/*** @author 笑小枫 <https://www.xiaoxiaofeng.com/>* @date 2023/12/21*/
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {/*** 接口分类：配置模块一的接口* 如果只有一个模块，删掉模块二即可* 如果有多个，可以继续配置*/@Bean(value = "exampleOne")public Docket exampleOne() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("笑小枫演示接口1").description("笑小枫演示接口1").termsOfServiceUrl("http://127.0.0.1:8080").contact(new Contact("笑小枫", "https://www.xiaoxiaofeng.com", "zfzjava@163.com")).version("1.0").build())//分组名称.groupName("笑小枫演示接口1").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.maple.knife4j.controller.one")).paths(PathSelectors.any()).build();}/*** 接口分类：配置模块二的接口*/@Bean(value = "exampleTwo")public Docket exampleTwo() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("笑小枫演示接口2").description("笑小枫演示接口2").termsOfServiceUrl("http://127.0.0.1:8080").contact(new Contact("笑小枫", "https://www.xiaoxiaofeng.com", "zfzjava@163.com")).version("1.0").build())//分组名称.groupName("笑小枫演示接口2").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.maple.rest.controller.two")).paths(PathSelectors.any()).build();}
}

👉第三步：创建两个不同目录的Controller，模拟上面的两个模块👇

com.maple.knife4j.controller.one.TestKnife4jOneController

package com.maple.knife4j.controller.one;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author 笑小枫 <https://www.xiaoxiaofeng.com/>* @date 2023/12/21*/
@Api(tags = "实例演示1-Knife4j接口文档")
@RestController
@RequestMapping("/one")
public class TestKnife4jOneController {@ApiOperation(value = "Knife4j接口文档演示")@GetMapping("/testKnife4j")public User testKnife4j(User param) {User user = new User();user.setName("笑小枫");user.setAge(18);user.setRemark("大家好，我是笑小枫，喜欢我的小伙伴点个赞呗，欢迎访问我的个人博客：https://www.xiaoxiaofeng.com");return user;}@Data@ApiModel("用户对象")static class User {@ApiModelProperty(value = "姓名")private String name;@ApiModelProperty(value = "年龄")private Integer age;@ApiModelProperty(value = "描述")private String remark;}
}

com.maple.knife4j.controller.one.TestKnife4jTwoController

package com.maple.knife4j.controller.two;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author 笑小枫 <https://www.xiaoxiaofeng.com/>* @date 2023/12/21*/
@Api(tags = "实例演示2-Knife4j接口文档")
@RestController
@RequestMapping("/two")
public class TestKnife4jTwoController {@ApiOperation(value = "Knife4j接口文档演示")@GetMapping("/testKnife4j")public User testKnife4j(User param) {User user = new User();user.setName("笑小枫");user.setAge(18);user.setRemark("大家好，我是笑小枫，喜欢我的小伙伴点个赞呗，欢迎访问我的个人博客：https://www.xiaoxiaofeng.com");return user;}@Data@ApiModel("用户对象")static class User {@ApiModelProperty(value = "姓名")private String name;@ApiModelProperty(value = "年龄")private Integer age;@ApiModelProperty(value = "描述")private String remark;}
}

2.3 看下页面效果👌

项目启动后，在浏览器输入http://127.0.0.1:6666/doc.html访问

image-20231221173516411

接口调试：

image-20231221173619001

2.4 增强模式😦

更多的增强模式使用可以参考官方文档增强模式

Knife4j自2.0.6版本开始,将目前在Ui界面中一些个性化配置剥离,开发者可以在后端进行配置，并且提供的knife4j-spring-boot-strater组件自动装载

spring.factories配置如下：

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration

在Spring Boot配置文件中,完整的配置如下:

knife4j:enable: truedocuments:-group: 2.X版本name: 接口签名locations: classpath:sign/*setting:language: zh-CNenableSwaggerModels: trueenableDocumentManage: trueswaggerModelName: 实体类列表enableVersion: falseenableReloadCacheParameter: falseenableAfterScript: trueenableFilterMultipartApiMethodType: POSTenableFilterMultipartApis: falseenableRequestCache: trueenableHost: falseenableHostText: 192.168.0.193:8000enableHomeCustom: truehomeCustomLocation: classpath:markdown/home.mdenableSearch: falseenableFooter: falseenableFooterCustom: truefooterCustomContent: Copyright  2022-[笑小枫](https://www.xiaoxiaofeng.com)enableDynamicParameter: falseenableDebug: trueenableOpenApi: falseenableGroup: truecors: falseproduction: falsebasic:enable: falseusername: testpassword: 123123

在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解

注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

各个配置属性说明如下：

属性默认值说明值
knife4j.enablefalse是否开启Knife4j增强模式
knife4j.corsfalse是否开启一个默认的跨域配置,该功能配合自定义Host使用
knife4j.productionfalse是否开启生产环境保护策略,详情参考文档
knife4j.basic对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.enablefalse关闭BasicHttp功能
knife4j.basic.usernamebasic用户名
knife4j.basic.passwordbasic密码
knife4j.documents自定义文档集合，该属性是数组
knife4j.documents.group所属分组
knife4j.documents.name类似于接口中的tag,对于自定义文档的分组
knife4j.documents.locationsmarkdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
knife4j.setting前端Ui的个性化配置属性
knife4j.setting.enableAfterScripttrue调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.languagezh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enableSwaggerModelstrue是否显示界面中SwaggerModel功能
knife4j.setting.swaggerModelNameSwagger Models重命名SwaggerModel名称,默认
knife4j.setting.enableDocumentManagetrue是否显示界面中"文档管理"功能
knife4j.setting.enableReloadCacheParameterfalse是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enableVersionfalse是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enableRequestCachetrue是否开启请求参数缓存
knife4j.setting.enableFilterMultipartApisfalse针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
knife4j.setting.enableFilterMultipartApiMethodTypePOST具体接口的过滤类型
knife4j.setting.enableHostfalse是否启用Host
knife4j.setting.enableHomeCustomfalse是否开启自定义主页内容
knife4j.setting.homeCustomLocation主页内容Markdown文件路径
knife4j.setting.enableSearchfalse是否禁用Ui界面中的搜索框
knife4j.setting.enableFootertrue是否显示Footer
knife4j.setting.enableFooterCustomfalse是否开启自定义Footer
knife4j.setting.footerCustomContentfalse自定义Footer内容
knife4j.setting.enableDynamicParameterfalse是否开启动态参数调试功能
knife4j.setting.enableDebugtrue启用调试
knife4j.setting.enableOpenApitrue显示OpenAPI规范
knife4j.setting.enableGrouptrue显示服务分组

关于个性化文档(knife4j.documents)以及个性化设置(knife4j.setting),有一些细微的区别,开发者在配置文件中进行配合好后,还需要在创建Docket对象时调用Knife4j提供的扩展Extesions进行赋值

示例代码如下：

package com.maple.knife4j.config;import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import lombok.AllArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;/*** @author 笑小枫 <https://www.xiaoxiaofeng.com/>* @date 2023/12/21*/
@Configuration
@EnableSwagger2WebMvc
@AllArgsConstructor
public class Knife4jConfiguration {/*** 引入Knife4j提供的扩展类*/private final OpenApiExtensionResolver openApiExtensionResolver;/*** 接口分类：配置模块一的接口* 如果只有一个模块，删掉模块二即可* 如果有多个，可以继续配置*/@Bean(value = "exampleOne")public Docket exampleOne() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("笑小枫演示接口1").description("笑小枫演示接口1").termsOfServiceUrl("http://127.0.0.1:8080").contact(new Contact("笑小枫", "https://www.xiaoxiaofeng.com", "zfzjava@163.com")).version("1.0")//赋予插件体系.build())//分组名称.groupName("笑小枫演示接口1").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.maple.knife4j.controller.one")).paths(PathSelectors.any()).build()//赋予插件体系.extensions(openApiExtensionResolver.buildExtensions("笑小枫演示接口1"));}/*** 接口分类：配置模块二的接口*/@Bean(value = "exampleTwo")public Docket exampleTwo() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("笑小枫演示接口2").description("笑小枫演示接口2").termsOfServiceUrl("http://127.0.0.1:8080").contact(new Contact("笑小枫", "https://www.xiaoxiaofeng.com", "zfzjava@163.com")).version("1.0").build())//分组名称.groupName("笑小枫演示接口2").select()//这里指定Controller扫描包路径.apis(RequestHandlerSelectors.basePackage("com.maple.rest.controller.two")).paths(PathSelectors.any()).build();}
}

buildExtensions方法需要传入分组名称,该分组名称主要是为了区分开发者在构建自定义文档时，在不同的Docket逻辑分组下进行区别显示。

OpenApiExtensionResolver辅助类需要配置knife4j.enable=true才能自动@Autowired

增强效果开启后,在最终调用接口时，Knife4j会添加扩展属性x-openapi,如下图：

image-20220630132424363

更多功能，请参考官方文档：https://doc.xiaominfo.com/knife4j/

3. 项目源码💕

本文到此就结束了，如果帮助到你了，帮忙点个赞👍

本文源码：https://github.com/hack-feng/maple-product/tree/main/maple-knife4j

🐾我是笑小枫，全网皆可搜的【笑小枫】

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.hqwc.cn/news/458755.html

如若内容造成侵权/违法违规/事实不符，请联系编程知识网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

Vagrant 虚拟机工具基本操作指南

Vagrant 虚拟机工具基本操作指南

Vagrant 虚拟机工具基本操作指南 ​#虚拟机 #​ ​#vargant#​ ​#ubuntu#​ ‍ 虚拟机virtualbox ,VMWare及WSL等大家都很了解了&#xff0c;那Vagrant是什么东西&#xff1f; 它是一组命令行工具&#xff0c;可以象Docker管理容器一样管理虚拟机&#xff0c;这样快速创…
阅读更多...
使用阿里云一键部署 幻兽帕鲁服务器 菜鸟教程 一键快速部署

使用阿里云一键部署 幻兽帕鲁服务器 菜鸟教程 一键快速部署

本文通过介绍如何 从购买阿里云服务器&#xff08;windows系统&#xff09;、到一键傻瓜式快速部署、再到连接到帕鲁服务器&#xff0c;简介明了&#xff0c;易上手&#xff0c;没相关专业知识的游戏玩家也能一键傻瓜式搭建服务器环境。 背景&#xff1a;最近很火爆的游戏《幻…
阅读更多...
C程序训练：二分查找法的应用之2

C程序训练：二分查找法的应用之2

本文来自&#xff1a;C程序训练&#xff1a;二分查找法的应用之2 在《C程序训练&#xff1a;二分查找法的应用》一文中介绍了利用二分查找计算某个区间中数的个数&#xff0c;本文介绍利用二分查找法计算数列中出现单个数字的位置。题目描述如下。 题目描述&#xff1a;一维整…
阅读更多...
初识C语言·预处理详解

初识C语言·预处理详解

目录 1 预定义符号 2 define定义常量 3 #define定义宏 4 带有副作用的宏 5 宏替换的规则 6 宏和函数的对比 7 # 和 ## i) #运算符 ii) ##运算符 8 命名约定 9 命令行定义 10 条件编译 条件编译1&#xff1a; 条件编译2&#xff1a; 条件编译3&#xff1a; 条件…
阅读更多...
嵌入式学习Day14 C语言 --- 位运算

嵌入式学习Day14 C语言 --- 位运算

位运算 注意&#xff1a;符号位也遵循这个规则 一、按位与(&) 运算规则&#xff1a;一假则假 int a 0x33;a & 0x55;0011 00110101 0101 &----------0001 0001 //0x11 二、按位或(|) 运算规则&#xff1a;一真则真 int a 0x33;a |0x55;0011 00110101 0101 |…
阅读更多...
JVM系列——垃圾收集器Parrlel Scavenge、CMS、G1常用参数和使用场景

JVM系列——垃圾收集器Parrlel Scavenge、CMS、G1常用参数和使用场景

背景 当前在Java领域&#xff0c;JDK 8版本仍然享有广泛的使用&#xff0c;它支持了Parallel Scavenge、CMS和G1这几种垃圾收集器。因此&#xff0c;为了在业务应用中更加高效地进行开发和性能调优&#xff0c;我们需要对这些垃圾收集器的工作原理和特性有一个全面的理解和认识…
阅读更多...
零基础学Python之面向对象

零基础学Python之面向对象

1.面向对象编程简介 &#xff08;1&#xff09;什么是面向对象 面向对象程序设计(Object Oriented Programming)作为一种新方法&#xff0c;其本质是以建立模型体现出来的抽象思维过程和面向对象的方法。模型是用来反映现实世界中事物特征的。任何一个模型都不可能反映客观事…
阅读更多...
Windows Server 2019 DHCP服务器搭建

Windows Server 2019 DHCP服务器搭建

系列文章目录 目录 系列文章目录 文章目录 前言 一、DHCP服务器是什么&#xff1f; 二、配置服务器 1.实验环境搭建 1)实验服务器配置和客户端 2)实验环境 2.服务器配置 ​编辑 文章目录 Windows Server 2003 Web服务器搭建Windows Server 2003 FTP服务器搭建Windows S…
阅读更多...
基于Java农产品商城系统设计与实现（源码+部署文档）

基于Java农产品商城系统设计与实现（源码+部署文档）

博主介绍&#xff1a; ✌至今服务客户已经1000、专注于Java技术领域、项目定制、技术答疑、开发工具、毕业项目实战 ✌ &#x1f345; 文末获取源码联系 &#x1f345; &#x1f447;&#x1f3fb; 精彩专栏 推荐订阅 &#x1f447;&#x1f3fb; 不然下次找不到 Java项目精品实…
阅读更多...
Dataway工具(一个接口竟然可以如此简单的配置出来无需开发任何一行代码，也不需要做任何 Mapping 实体映射绑定。)

Dataway工具(一个接口竟然可以如此简单的配置出来无需开发任何一行代码，也不需要做任何 Mapping 实体映射绑定。)

基于 DataQL 服务聚合能力&#xff0c;为应用提供的一个接口配置工具&#xff0c;使得使用者无需开发任何代码就配置一个满足需求的接口。整个接口配置、测试、冒烟、发布&#xff0c;一站式都通过 Dataway 提供的 UI 界面完成。UI 会以 Jar 包方式提供并集成到应用中并和应用共…
阅读更多...
生产问题-Java服务CPU飙升100%问题

生产问题-Java服务CPU飙升100%问题

情况回顾 最近运维同学反馈有微服务CPU飙升100%&#xff0c;根据dump的日志文件排查出问题所在&#xff0c;在这里给大家做简单的分享&#xff0c;希望给大家工作上可以带来帮助。 核心伪代码分析 SneakyThrows//包装成 RuntimeException &#xff0c;骗过编译器&#xff0c…
阅读更多...
navigator.mediaDevices.getUserMedia获取本地音频/麦克权限并提示用户

navigator.mediaDevices.getUserMedia获取本地音频/麦克权限并提示用户

navigator.mediaDevices.getUserMedia获取本地音频/麦克权限并提示用户 效果获取权限NotFoundErrorNotAllowedError 代码 效果 获取权限 NotFoundError NotAllowedError 代码 // 调用 captureLocalMedia()// 方法 function captureLocalMedia() {console.warn(Requesting lo…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023