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.mzph.cn/news/672324.shtml

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

相关文章

【Java程序设计】【C00187】基于SSM的旅游资源网站管理系统(论文+PPT)

基于SSM的旅游资源网站管理系统&#xff08;论文PPT&#xff09; 项目简介项目获取开发环境项目技术运行截图 项目简介 这是一个基于ssm的旅游资源网站 本系统分为前台系统、用户和管理员3个功能模块。 前台系统&#xff1a;当游客打开系统的网址后&#xff0c;首先看到的就是…

介绍 MSTest Runner – CLI、Visual Studio 等

作者&#xff1a;Amaury Lev Marco Rossignoli Jakub Jareš 排版&#xff1a;Alan Wang 我们很高兴推出 MSTest 运行器&#xff0c;这是一款全新的轻量级 MSTest 测试运行器。这个新的运行器使测试更加便携和可靠&#xff0c;运行速度更快&#xff0c;并且具有可扩展性&#x…

React+Antd+tree实现树多选功能(选中项受控+支持模糊检索)

1、先上效果 树型控件&#xff0c;选中项形成一棵新的树&#xff0c;若父选中&#xff0c;子自动选中&#xff0c;子取消&#xff0c;父不取消&#xff0c;子选中&#xff0c;所有的父节点自动取消。同时支持模糊检索&#xff0c;会检索出所有包含该内容的关联节点。 2、环境准…

centos 7.6 安装cas 对接ldap 单点登录实战

centos 7.6 安装cas 对ldap 单点登录实战 1、安装前准备工作1.1、centos 7.6 安装JDK 1.81.2、centos 7 安装tomcat 9.0.841.3、windows10 安装JDK 1.81.4、windows10 安装打包工具 maven 3.9.6 2、下载cas 5.3 并打包成war包3、部署cas到tomcat4、cas对接ldap 1、安装前准备工…

回归预测 | Matlab实现POA-BP鹈鹕算法优化BP神经网络多变量回归预测

回归预测 | Matlab实现POA-BP鹈鹕算法优化BP神经网络多变量回归预测 目录 回归预测 | Matlab实现POA-BP鹈鹕算法优化BP神经网络多变量回归预测预测效果基本描述程序设计参考资料 预测效果 基本描述 1.Matlab实现POA-BP鹈鹕算法优化BP神经网络多变量回归预测&#xff08;完整源码…

【UE】游戏运行流程的简单理解

流程图 官方的游戏流程图&#xff1a; 一般顺序为初始化引擎、创建并初始化 GameInstance、加载关卡&#xff0c;最后开始游戏。 总的来说就是&#xff1a; 开始游戏-》游戏实例-》关卡-》游戏模式-》玩家控制器-》Pawn、玩家状态、HUD、UMG&#xff08;可有可无&#xff09; …

RabiitMQ延迟队列(死信交换机)

Dead Letter Exchange&#xff08;死信交换机&#xff09; 在MQ中&#xff0c;当消息成为死信&#xff08;Dead message 死掉的信息&#xff09;后&#xff0c;消息中间件可以将其从当前队列发送到另一个队列中&#xff0c;这个队列就是死信队列。而 在RabbitMQ中&#xff0c;由…

二、SSM 整合配置实战

本章概要 依赖整合和添加控制层配置编写(SpringMVC 整合)业务配置编写(AOP/TX 整合)持久层配置编写(MyBatis 整合)容器初始化配置类整合测试 2.1 依赖整合和添加 数据库准备 数据库脚本 CREATE DATABASE mybatis-example;USE mybatis-example;CREATE TABLE t_emp(emp_id INT…

【C#】MVVM架构

示例结果展示 前提了解 MVVM是Model-View-ViewModel的缩写形式,它通常被用于WPF或Silverlight开发。 Model——可以理解为带有字段,属性的类。例如学校类,教师类,学生类等 View——可以理解为我们所看到的UI。前端界面。 View Model在View和Model之间,起到连接的作用,…

2024-02-06(Sqoop)

1.Sqoop Apache Sqoop是Hadoop生态体系和RDBMS&#xff08;关系型数据库&#xff09;体系之间传递数据的一种工具。 Sqoop工作机制是将导入或者导出命令翻译成MapReduce程序来实现。在翻译出的MapReduce中主要是对inputformat和outputformat进行定制。 Hadoop生态包括&#…

Swift Combine 从入门到精通一

1. Combine 简介 用 Apple 官方的话来说&#xff0c;Combine 是: a declarative Swift API for processing values over time. Combine 是 Apple 用来实现函数响应式编程的库&#xff0c; 类似于 RxSwift。 RxSwift 是 ReactiveX 对 Swift 语言的实现。 Combine 使用了许多可以…

8868助力意甲尤文图斯足球俱乐部 寻求冬窗阵容补强

意甲的尤文图斯足球俱乐部是8868合作体育球队之一&#xff0c;根据意大利天空体育的消息&#xff0c;尤文图斯希望在冬季转会窗口通过引援来加强球队的实力&#xff0c;特别是在中场位置。但尤文必须卖掉一部分人来筹集资金&#xff0c;而伊林就在名单的最前面。 尤文想要提高自…

Android.mk 语法详解

一.Android.mk简介 Android.mk 是Android 提供的一种makefile 文件,注意用来编译生成&#xff08;exe&#xff0c;so&#xff0c;a&#xff0c;jar&#xff0c;apk&#xff09;等文件。 二.Android.mk编写 分析一个最简单的Android.mk LOCAL_PATH : $(call my-dir) //定义了…

常见web安全漏洞和解决思路

一、常见安全漏洞 服务器类安全漏洞&#xff1a; 服务器含服务器软件类型较多&#xff0c;此次不再一一列举&#xff1b; WEB访问类安全漏洞&#xff1a; XSS漏洞检测 (key: xss) SQL 注入检测 (key: sqldet) 命令/代码注入检测 (key: cmd-injection) …

解决计算机“缺失ffmpeg.dll”报错?修复ffmpeg.dll文件方案

在计算机使用过程中&#xff0c;我们经常会遇到一些错误提示&#xff0c;其中之一就是“ffmpeg.dll丢失”。ffmpeg.dll是FFmpeg多媒体框架中的一个重要组件&#xff0c;它负责处理音频和视频的编解码。当打开某些软件时&#xff0c;如果系统找不到该文件&#xff0c;就会出现这…

每天分享5款软件,让大家工作学习更顺心

​ 快乐不是在于拥有什么,而在于我们和别人分享什么。每天分享五款工具&#xff0c;让大家工作办公更顺心就是我最大的快乐。 1.图片放大增强——Upscayl ​ Upscayl是一款图片放大增强软件&#xff0c;可以利用人工智能技术将低分辨率的图片转换为高分辨率的图片&#xff0c…

Java应用中各类环境变量的优先级及最佳实践

1.引言 Java应用程序的开发和部署过程中&#xff0c;合理利用各类环境变量是关键之一。不同类型的环境变量&#xff0c;如系统环境变量、进程级环境变量、Java启动参数设置的系统属性以及Spring Boot配置文件中的环境变量&#xff0c;它们之间存在优先级差异。 深入理解这些环…

【C生万物】C语言数据类型、变量和运算符

&#x1f4da;博客主页&#xff1a;爱敲代码的小杨. ✨专栏&#xff1a;《Java SE语法》 | 《数据结构与算法》 | 《C生万物》 ❤️感谢大家点赞&#x1f44d;&#x1f3fb;收藏⭐评论✍&#x1f3fb;&#xff0c;您的三连就是我持续更新的动力❤️ &#x1f64f;小杨水平有…

【日志记录】——单片机可执行文件合并

一&#xff1a;需求场景 现在有一片单片机&#xff0c;执行程序包括自定义boot和应用程序app, 在将打包好的固件给到生产时有以下问题&#xff0c;由于要通过jlink烧录boot&#xff0c;然后上电启动boot&#xff0c;通过boot烧录初始化程序&#xff0c;过程过于复杂&#xff0…

Java Map HashMap集合的基本操作与使用

Java Map HashMap集合的基本操作与使用 package com.zhong.mapdemo.map;import jdk.jfr.Description;import javax.swing.plaf.synth.SynthOptionPaneUI; import java.util.*;/*** ClassName : MapDemo* Description : map 的基本使用* Author : zhx* Date: 2024-02-07 10:29*/…