Springboot 3项目整合Knife4j接口文档(接口分组详细教程)
文章目录
- 前言
- 一、Spring Boot 3.0整合Knife4j
- 二、OpenApi 3注解的使用规范
- 三、使用步骤
-
- 1.Spring Boot 3.0项目中使用knife4j
- 2.在application.yml中添加knife4j相关配置
- 3.设置WebMvc相关配置(解决封装统一异常处理后doc.html无法打开的问题)
- 4.创建Knife4j的配置文件
- 5.添加实体类信息
- 6.在controller下新建security和system文件夹,添加相应接口进行测试
- 四、重启项目并访问接口文档
- 五、Springboot启动类优化
前言
springboot 3开始javax包改成了jakarta,而swagger-oas等包中依然使用的是javax,所以报错。另外springfox已经停止更新有段时间了,并且不支持OpenAPI 3标准,升级Springboot 3.0以后会有更多问题暴露出来。而SpringBoot 3只支持OpenAPI 3规范,因此Spring官网推荐了Springdoc
OpenApi 3的规范,目前针对Java的Spring Boot项目,主要支持的有2个版本:
- springfox 3.0.0: 同时兼容OpenAPI 2以及OpenAPI 3,但是停更很久了
- springdoc-openapi:兼容OpenAPI 3规范,更新速度频繁
- Knife4j:在只有的OpenAPI 3规范中,底层基础框架选择springdoc-openapi项目,针对Springfox 3.0.0版本会放弃
一、Spring Boot 3.0整合Knife4j
以下是一些常见的Spring Boot版本及其对应的Knife4j版本兼容推荐:
Spring Boot版本
Knife4j Swagger 2规范
Knife4j OpenAPI 3规范
1.5.x ~ 2.0.0
< Knife4j 2.0.0
>= Knife4j 4.0.0
2.0 ~ 2.2
Knife4j 2.0.0 ~ 2.0.6
>= Knife4j 4.0.0
2.2.x ~ 2.4.0
Knife4j 2.0.6 ~ 2.0.9
>= Knife4j 4.0.0
2.4.0 ~ 2.7.x
>= Knife4j 4.0.0
>= Knife4j 4.0.0
>= 3.0
>= Knife4j 4.0.0
>= Knife4j 4.0.0
参考文档:关于Knife4j适配不同Spring Boot版本的说明文档
项目配置:
JDK:23
SpringBoot:3.3.1
Knife4j:4.5.0
温馨提示:
二、OpenApi 3注解的使用规范
- Swagger 3(OpenApi 3) 注解与Swagger 2注解的对比
Swagger 2
OpenAPI 3
注解位置
作用
@Api
@Tag(name = “接口类名”,description = “接口类描述”)
Controller类
描述此controller的信息
@ApiOperation(value = “接口方法描述”)
@Operation(summary =“接口方法描述”)
Api端口方法
描述此Api的信息
@ApiImplicitParams
@Parameters
Api端口方法
描述参数信息
@ApiImplicitParam
@Parameter(description=“参数描述”)
Api方法的参数
描述参数信息
@ApiParam
@Parameter(description=“参数描述”)
Api方法的参数
-
@ApiIgnore
@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden
-
用在各种地方,用于隐藏其Api
@ApiModel
@Schema
DTO类
用于Entity,以及Entity的属性上
@ApiModelProperty
@Schema
DTO属性
用于Entity,以及Entity的属性上
参考链接: 从 Springfox Swagger 2 迁移到 Springdoc Open API
三、使用步骤
1.Spring Boot 3.0项目中使用knife4j
-
在pom.xml文件中导入knife4j的依赖(本文springboot的版本是3.3.1)
com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter 4.5.0
其实现在就可以使用Knife4j了,暂不做其他配置,启动项目,浏览器输入http://localhost:8080/doc.html查看接口文档
- 由于我们没有进行任何的属性配置,所以看到的页面是knife4j的初始页面
2.在application.yml中添加knife4j相关配置
# knife4j的增强配置,不需要增强可以不配
knife4j:enable: true # 开启knife4j,无需添加@EnableKnife4j注解setting:language: zh_cn #中文swagger-model-name: 实体列表 #默认为: Swagger Modelsbasic: # 开启Swagger的Basic认证功能,默认是falseenable: trueusername: adminpassword: 123456
3.设置WebMvc相关配置(解决封装统一异常处理后doc.html无法打开的问题)
-
定义一个编码格式常量类,里面存储静态资源地址(封装起来便于使用和维护)
package com.patrick.blog.constant;
/**
-
-
编码格式常量类
-
@author Patrick
-
@since 2025-1-1
*/
public class SystemConstant {/**
-
Knife4j接口文档接口分组和分组路径
*/
public static class Knife4j {/**
- 接口分组
*/
public static final String SECURITY = “权限管理”;
public static final String SYSTEM = “系统管理”;
/**
- 接口分组路径
*/
public static final String SECURITY_PATH = “com.patrick.blog.controller.security”;
public static final String SYSTEM_PATH = “com.patrick.blog.controller.system”;
}
- 接口分组
/**
-
编码常量
*/
public static class Charset {/**
- 编码格式设置
*/
public static final String JSON_TYPE_UTF8_CHARSET = “application/json;charset=UTF-8”;
- 编码格式设置
}
/*** 允许匿名访问的静态资源路径列表*/public static final String[] STATIC_WITHE_PATH_LIST = new String[]{"/","/js/**","/css/**","/img/**","/fonts/**","/index.html","/favicon.ico","/doc.html","/swagger-ui.html","/webjars/**","/swagger-resources/**","/v3/**"};/*** 允许匿名访问的静态资源存放位置列表*/public static final String[] STATIC_WITHE_LOCATION_LIST = new String[]{"classpath:/static/","classpath:/public/","classpath:/META-INF/resources/"};
}
-
}
-
-
定义系统配置类WebMvcConfig,由于knife4j接口文档属于静态资源,需将相关资源放行
package com.patrick.blog.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;import static com.patrick.blog.constant.SystemConstant.Permission.*;
/**
-
-
设置WebMvc相关配置
-
@author Patrick
-
@since 2025-1-1
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {/**
-
解决resources下的静态资源无法访问
-
@param registry 资源映射注册器
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {// 静态资源映射
registry.addResourceHandler(STATIC_WITHE_PATH_LIST)
.addResourceLocations(STATIC_WITHE_LOCATION_LIST)
.setCachePeriod(0);
}
-
}
-
4.创建Knife4j的配置文件
-
该文件主要进行Knife4j的属性配置,如:标题、版本、作者信息、接口分组等
package com.patrick.blog.config;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import static com.patrick.blog.constant.SystemConstant.Knife4j.*;
/**
-
-
Knife4j配置类
-
@author Patrick
-
@since 2025-1-1
*/
@Configuration
public class Knife4jConfig {/**
- 创建权限分组api
*/
@Bean
public GroupedOpenApi securityApi() {
return createRestApi(SECURITY, SECURITY_PATH);
}/**
- 创建系统分组api
*/
@Bean
public GroupedOpenApi systemApi() {
return createRestApi(SYSTEM, SYSTEM_PATH);
}/**
- 创建api
- @param groupName 分组名称
- @param basePackage 包路径
- @return GroupedOpenApi
*/
public GroupedOpenApi createRestApi(String groupName, String basePackage) {
return GroupedOpenApi.builder()
.group(groupName) // 分组名称
.packagesToScan(basePackage) // 扫描的包路径
.pathsToMatch(“/**”) // 匹配所有路径
.addOpenApiCustomizer(openApi -> openApi.info(apiInfo())) // 设置api信息
.build();
}
/**
- api简介信息
- @return ApiInfo
*/
private Info apiInfo() {
return new Info()
.title(“Patrick后台管理系统服务接口”) // 标题
.description(“Patrick后台管理系统服务接口文档…”) // 描述
.version(“1.0.0”) // 版本号
.termsOfService(“http://doc.xiaominfo.com”) // 服务条款
.contact(new Contact().name(“Patrick”).url(“https://github.com/Patrick-Luo-THR”).email(“patrick.luo@163.com”)) // 联系人信息
.license(new License().name(“Apache 2.0”).url(“http://www.apache.org/licenses/LICENSE-2.0.html”)); // 许可证信息
}
}
-
5.添加实体类信息
@Schema(description = “ ”): 标记实体类属性
@Data
@TableName("t_user")
@Schema(description = "用户实体")
public class User implements Serializable {@Schema(description = "用户id")private Integer id;@Schema(description = "用户昵称")private String nickname;@Schema(description = "用户名")private String username;@Schema(description = "用户密码")private String password;}
6.在controller下新建security和system文件夹,添加相应接口进行测试
@Tag(name = “ ”): 标记接口类别
@Operation(summary =“ ”): 标记接口操作
-
创建(create) – 使用Post方法;
-
修改(update) – 使用Post方法;
-
删除(delete) – 使用Delete方法;
@RestController
@Tag(name = “用户管理”)
@RequestMapping(“/user”)
public class UserController {@Autowired UserService userService;/*** 用户列表* @return*/ @Operation(summary = "用户列表") @GetMapping("/list") public JsonResult list() {List<User> userList = userService.findAll();return JsonResult.success().data("userList", userList); }
}
四、重启项目并访问接口文档
- 访问http://localhost:8080/doc.html,可以看到我们配置的属性已经在页面中显示出来了
五、Springboot启动类优化
-
每次都需要打开浏览器输入地址访问,对开发者很不友好,因此采取以下优化
@Slf4j
@SpringBootApplication
public class BlogApplication {public static void main(String[] args) {ConfigurableEnvironment env = SpringApplication.run(BlogApplication.class, args).getEnvironment();log.info("
" +"Application: '{}' is running Success! " +"Local URL: http://localhost:{} " +"Document: http://localhost:{}/doc.html
" +
“----------------------------------------------------------”,
env.getProperty(“spring.application.name”),
env.getProperty(“server.port”),
env.getProperty(“server.port”));
}}
-
项目启动,控制台打印日志如下:
相关文章:

Springboot 3项目整合Knife4j接口文档(接口分组详细教程)
文章目录 前言一、Spring Boot 3.0整合Knife4j二、OpenApi 3注解的使用规范三、使用步骤 1.Spring Boot 3.0项目中使用knife4j2.在application.yml中添加knife4j相关配置3.设置WebMvc相关配置(解决封装统一异常处理后doc.html无法打开的问题)4.创建Knif…...
深入解析 Conda 安装的默认依赖包及其作用:conda create安装了哪些包(中英双语)
深入解析 Conda 安装的默认依赖包及其作用 当我们使用 Conda 创建新环境时,例如执行命令: conda create -n olmes python3.10Conda 会自动为我们安装一系列基础依赖包,保证 Python 环境能够正常运行。这些包不仅是我们开发的基础工具&#…...
Redis核心技术知识点全集
Redis数据结构和常用命令 1. String字符串2. Hash哈希3. List列表4. Set集合5. Sorted Set有序集合6. Redis常用命令参考Redis事务机制...
【Unity3D】ECS入门学习(九)SystemBase
SystemBase:支持主线程或多线程执行筛选实体任务。 主要介绍是内部成员:Entities的各种筛选方法,其内部成员还有EntityManager ForEach方法筛选,传递一个有参委托函数进去,参数ref xxx组件类(可填多个&…...

【Triton-ONNX】如何使用 ONNX 模型服务与 Triton 通信执行推理任务上-Triton快速开始
模型部署系列文章 前置-docker 理解:【 0 基础 Docker 极速入门】镜像、容器、常用命令总结前置-http/gRPC 的理解: 【HTTP和gRPC的区别】协议类型/传输效率 /性能等对比【保姆级教程附代码】Pytorch (.pth) 到 TensorRT (.plan) 模型转化全流程【保姆级教程附代码(二)】Pytor…...

CertiK《Hack3d:2024年度安全报告》(附报告全文链接)
CertiK《Hack3d:2024年度安全报告》现已发布,本次报告深入分析了2024年Web3.0领域的安全状况。2024年损失总额超过23亿美元,同比增幅高达31.61%;其中,12月的损失金额最少。过去一年,网络钓鱼攻击和私钥泄露…...

TIOBE 指数 12 月排行榜公布,VB.Net排行第九
IT之家 12 月 10 日消息,TIOBE 编程社区指数是一个衡量编程语言受欢迎程度的指标,评判的依据来自世界范围内的工程师、课程、供应商及搜索引擎,今天 TIOBE 官网公布了 2024 年 12 月的编程语言排行榜,IT之家整理如下: …...

【网络协议】开放式最短路径优先协议OSPF详解(一)
OSPF 是为取代 RIP 而开发的一种无类别的链路状态路由协议,它通过使用区域划分以实现更好的可扩展性。 文章目录 链路状态路由协议OSPF 的工作原理OSPF 数据包类型Dijkstra算法、管理距离与度量值OSPF的管理距离OSPF的度量值 链路状态路由协议的优势拓扑结构路由器O…...
嵌入式Linux驱动开发的基本知识(驱动程序的本质、常见的设备类型、设备号的本质理解、设备实例的注册过程)
基本概念之什么是驱动程序()? 驱动程序本质上是代码逻辑的集合,通常用于管理、驱动多个设备实例。某个设备要想使用驱动程序,需要实例化相应的驱动程序的结构体,并在系统中注册,获得主设备号、次设备号,并…...

爱死机第四季(秘密关卡)4KHDR国语字幕
通过网盘分享的文件:love_death_robot 链接: https://pan.baidu.com/s/1bG3Xtdopenil2O_y93hY_g?pwd8kib 提取码: 8kib...
kubelet状态错误报错
journalctl -xeu kubelet 执行后的日志如下: -- -- The process exit code is exited and its exit status is 1. Jan 02 14:20:06 iv-ydipyqxfr4wuxjsij0bd systemd[1]: kubelet.service: Failed with result exit-code. -- Subject: Unit failed -- Defined-By: system…...
<div>{{ $t(“collectionPlan“) }}</div> 中的$t是什么
$t是Vue I18n插件提供的一种方法,用于根据当前应用的语言环境来获取相应的翻译文本。 以下是一个简单的示例,展示如何在Vue I18n中定义消息: const i18n new VueI18n({locale: en, // 设置默认语言messages: {en: {collectionPlan: Collec…...
[C++刷题] 求回文素数
求回文素数 题目 素数回文数的个数 题目描述 求 11 11 11 到 n n n 之间(包括 n n n),既是素数又是回文数的整数有多少个。 输入格式 一个大于 11 11 11 小于 10000 10000 10000 的整数 n n n。 输出格式 11 11 11 到 n n n 之…...
SQLALchemy如何将SQL语句编译为特定数据库方言
最近在一个使用fastapitortoise-orm的项目中,需要将orm的语句编译成特定数据库方言,但是查询了官方文档及一些资料却找不到合适的方法论😔,于是乎我就把目光放到了sqlalchemy身上,东找西找给我找着了。话不多说&#x…...

[卫星遥感] 解密卫星目标跟踪:挑战与突破的深度剖析
目录 [卫星遥感] 解密卫星目标跟踪:挑战与突破的深度剖析 1. 卫星目标跟踪的核心挑战 1.1 目标的高速与不确定性 1.2 卫星传感器的局限性 1.3 数据处理与融合问题 1.4 大尺度与实时性要求 2. 当前卫星目标跟踪的主流技术 2.1 卡尔曼滤波(Kalman …...

I2C(一):存储器模式:stm32作为主机对AT24C02写读数据
存储器模式:在HAL库中,I2C有专门对存储器外设设置的库函数 I2C(一):存储器模式的使用 1、I2C轮询式写读AT24C02一页数据2、I2C轮询式写读AT24C02多页数据3、I2C中断式写读AT24C02一页数据4、I2C使用DMA式写读AT24C02一…...
scrapy 教程
Scrapy Tutorial In this tutorial, we’ll assume that Scrapy is already installed on your system. If that’s not the case, see Installation guide. We are going to scrape quotes.toscrape.com, a website that lists quotes from famous authors. This tutorial …...

2025元旦源码免费送
我们常常在当下感到时间慢,觉得未来遥远,但一旦回头看,时间已经悄然流逝。对于未来,尽管如此,也应该保持一种从容的态度,相信未来仍有许多可能性等待着我们。 免费获取源码。 更多内容敬请期待。如有需要可…...
高级架构五 设计模式
一 设计模式七大原则 1.1. 设计模式目的 编写软件过程中,程序员面临着来自 耦合性,内聚性以及可维护性,可扩展性,重用性,灵活性 等多方面的挑战,设计模式是为了让程序(软件),具有更好的&#…...

RFID手持机与RFID工业平板在仓储物流管理系统中的选型
概述 随着物联网技术在仓储物流管理系统中的普及,RFID手持机与RFID工业平板作为基于RFID技术手持式读写器的两种重要终端设备形态,得到了广泛应用。尽管RFID手持机与RFID工业平板都具备读写 RFID标签的基本功能,使用场景较为类似,…...

网络编程(Modbus进阶)
思维导图 Modbus RTU(先学一点理论) 概念 Modbus RTU 是工业自动化领域 最广泛应用的串行通信协议,由 Modicon 公司(现施耐德电气)于 1979 年推出。它以 高效率、强健性、易实现的特点成为工业控制系统的通信标准。 包…...
应用升级/灾备测试时使用guarantee 闪回点迅速回退
1.场景 应用要升级,当升级失败时,数据库回退到升级前. 要测试系统,测试完成后,数据库要回退到测试前。 相对于RMAN恢复需要很长时间, 数据库闪回只需要几分钟。 2.技术实现 数据库设置 2个db_recovery参数 创建guarantee闪回点,不需要开启数据库闪回。…...

Spark 之 入门讲解详细版(1)
1、简介 1.1 Spark简介 Spark是加州大学伯克利分校AMP实验室(Algorithms, Machines, and People Lab)开发通用内存并行计算框架。Spark在2013年6月进入Apache成为孵化项目,8个月后成为Apache顶级项目,速度之快足见过人之处&…...

基于ASP.NET+ SQL Server实现(Web)医院信息管理系统
医院信息管理系统 1. 课程设计内容 在 visual studio 2017 平台上,开发一个“医院信息管理系统”Web 程序。 2. 课程设计目的 综合运用 c#.net 知识,在 vs 2017 平台上,进行 ASP.NET 应用程序和简易网站的开发;初步熟悉开发一…...

大型活动交通拥堵治理的视觉算法应用
大型活动下智慧交通的视觉分析应用 一、背景与挑战 大型活动(如演唱会、马拉松赛事、高考中考等)期间,城市交通面临瞬时人流车流激增、传统摄像头模糊、交通拥堵识别滞后等问题。以演唱会为例,暖城商圈曾因观众集中离场导致周边…...
Unit 1 深度强化学习简介
Deep RL Course ——Unit 1 Introduction 从理论和实践层面深入学习深度强化学习。学会使用知名的深度强化学习库,例如 Stable Baselines3、RL Baselines3 Zoo、Sample Factory 和 CleanRL。在独特的环境中训练智能体,比如 SnowballFight、Huggy the Do…...
uniapp中使用aixos 报错
问题: 在uniapp中使用aixos,运行后报如下错误: AxiosError: There is no suitable adapter to dispatch the request since : - adapter xhr is not supported by the environment - adapter http is not available in the build 解决方案&…...

项目部署到Linux上时遇到的错误(Redis,MySQL,无法正确连接,地址占用问题)
Redis无法正确连接 在运行jar包时出现了这样的错误 查询得知问题核心在于Redis连接失败,具体原因是客户端发送了密码认证请求,但Redis服务器未设置密码 1.为Redis设置密码(匹配客户端配置) 步骤: 1).修…...

均衡后的SNRSINR
本文主要摘自参考文献中的前两篇,相关文献中经常会出现MIMO检测后的SINR不过一直没有找到相关数学推到过程,其中文献[1]中给出了相关原理在此仅做记录。 1. 系统模型 复信道模型 n t n_t nt 根发送天线, n r n_r nr 根接收天线的 MIMO 系…...

C++使用 new 来创建动态数组
问题: 不能使用变量定义数组大小 原因: 这是因为数组在内存中是连续存储的,编译器需要在编译阶段就确定数组的大小,以便正确地分配内存空间。如果允许使用变量来定义数组的大小,那么编译器就无法在编译时确定数组的大…...