Spring Boot 3.4.3 基于 SpringDoc 2 和 Swagger 3 实现项目接口文档管理
在现代企业级应用开发中,前后端分离已成为主流模式,前端负责界面呈现,后端专注提供 RESTful API 接口。然而,接口文档的编写和维护往往是开发过程中的痛点。Spring Boot 3.4.3 结合 SpringDoc 2 和 Swagger 3,为开发者提供了一种高效的方式,通过 OpenAPI 3 标准自动生成和管理接口文档。本文将详细介绍如何在 Spring Boot 3.4.3 中集成 SpringDoc 2 和 Swagger 3,构建标准化的接口文档,并附上完整的代码示例和单元测试指南。
1. SpringDoc 和 Swagger 简介
1.1 什么是 SpringDoc?
SpringDoc 是一个开源库,专为 Spring 框架设计,用于根据项目代码自动生成符合 OpenAPI 3.0 规范的 API 文档。它通过扫描控制器和注解,生成详细的接口信息,帮助开发者轻松创建和维护 RESTful API 文档。
1.2 Swagger 的作用
Swagger 是一个广受欢迎的 API 文档工具,Swagger 3 基于 OpenAPI 3.0 标准,提供可视化的接口文档界面(Swagger UI),支持在线查看和测试 API。SpringDoc 将 Swagger 的功能集成到 Spring 项目中,简化了配置流程。
1.3 优点
- 自动化:无需手动编写文档,减少维护成本。
- 标准化:遵循 OpenAPI 3.0,提供一致的文档格式。
- 交互性:Swagger UI 支持在线调试 API,提升开发效率。
2. 使用场景
SpringDoc 和 Swagger 适用于以下场景:
- 前后端分离:为前端提供清晰的接口说明。
- 团队协作:确保开发者和测试人员快速理解 API。
- 微服务架构:管理多个服务的接口文档。
- 快速迭代:接口变更时自动更新文档。
3. 项目实战
以下是基于 Spring Boot 3.4.3 集成 SpringDoc 2 和 Swagger 3 的完整步骤。
3.1 添加 Maven 依赖
在 pom.xml
中添加必要的依赖:
<dependencies><!-- Spring Boot Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- SpringDoc OpenAPI --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.0.2</version></dependency><!-- 测试支持 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
</dependencies>
说明:
springdoc-openapi-starter-webmvc-ui
集成了 Swagger UI 和 OpenAPI 3 支持。- Spring Boot 3.4.3 默认使用 Jakarta EE,无需额外处理兼容性问题。
3.2 创建 RESTful 接口
创建一个简单的控制器示例:
package cn.joyous.controller;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {@Operation(summary = "获取用户信息", description = "根据用户ID获取详细信息")@GetMapping("/user/{id}")public String getUser(@PathVariable("id") Long id) {return "User ID: " + id;}@Operation(summary = "创建用户", description = "新增一个用户")@PostMapping("/user")public String createUser(@RequestParam("name") String name) {return "User created: " + name;}
}
注解说明:
@Tag
:定义接口分组。@Operation
:描述接口的功能和详情。- SpringDoc 会根据这些注解生成文档。
3.3 配置 SpringDoc(可选)
SpringDoc 默认无需额外配置即可使用 Swagger UI。如果需要自定义文档信息,可以添加配置类:
package cn.joyous.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Spring Boot 3.4.3 API 文档").version("1.0.0").description("基于 SpringDoc 2 和 Swagger 3 的接口文档示例"));}
}
3.4 启动与访问
- 启动 Spring Boot 应用(默认端口 8080)。
- 访问 Swagger UI:
http://localhost:8080/swagger-ui/index.html
。 - 你将看到自动生成的接口文档,包括
/api/user/{id}
和/api/user
两个接口,支持在线测试。
4. 单元测试
为确保接口文档和功能正常运行,可以编写单元测试。
4.1 测试依赖
确保 pom.xml
已包含 spring-boot-starter-test
。
4.2 测试代码
创建一个测试类:
package cn.joyous.controller;import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;@SpringBootTest
@AutoConfigureMockMvc
public class UserControllerTest {@Autowiredprivate MockMvc mockMvc;@Testpublic void testGetUser() throws Exception {mockMvc.perform(get("/api/user/1")).andExpect(status().isOk()).andExpect(content().string("User ID: 1"));}
}
说明:
@SpringBootTest
:加载 Spring 上下文。@AutoConfigureMockMvc
:启用 MockMvc 用于模拟 HTTP 请求。- 测试验证了
/api/user/{id}
接口的正确性。
4.3 运行测试
在 IDE 中运行测试,确保接口返回预期结果。
5. 进阶配置(可选)
-
多环境支持
在SpringDocConfig
中配置不同环境的服务器地址:import io.swagger.v3.oas.models.servers.Server;@Bean public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档").version("1.0.0")).addServersItem(new Server().url("http://localhost:8080").description("开发环境")).addServersItem(new Server().url("https://api.example.com").description("生产环境")); }
-
分组接口
使用@Tag
或 SpringDoc 的分组功能分隔不同模块的接口:@Bean public GroupedOpenApi userApi() {return GroupedOpenApi.builder().group("user-api").pathsToMatch("/api/user/**").build(); }
-
安全性集成
若项目使用 Spring Security,可添加认证支持:@Bean public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档")).addSecurityItem(new SecurityRequirement().addList("bearerAuth")).components(new Components().addSecuritySchemes("bearerAuth",new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))); }
6. 总结
Spring Boot 3.4.3 结合 SpringDoc 2 和 Swagger 3,为接口文档管理提供了一套高效、标准化的解决方案。通过简单的依赖引入和少量配置,你可以快速生成交互式的 API 文档,极大提升开发效率和团队协作能力。本文从基础集成到单元测试,再到进阶配置,涵盖了完整实践过程,希望对你有所帮助。
相关文章:
Spring Boot 3.4.3 基于 SpringDoc 2 和 Swagger 3 实现项目接口文档管理
在现代企业级应用开发中,前后端分离已成为主流模式,前端负责界面呈现,后端专注提供 RESTful API 接口。然而,接口文档的编写和维护往往是开发过程中的痛点。Spring Boot 3.4.3 结合 SpringDoc 2 和 Swagger 3,为开发者…...
前端D3.js面试题及参考答案
目录 解释 D3.js 中 enter ()、update ()、exit () 的作用及典型应用场景 描述数据连接(Data Join)的原理,如何通过 data () 方法实现数据集与 DOM 元素的动态绑定? 如何利用 datum () 实现单个元素的数据绑定?与 data () 有何区别? 在动态数据更新时,如何通过 merge…...
Docker实现MySQL主从复制配置【简易版】
Docker实现MySQL主从复制配置 环境准备 安装docker 拉取MySQL 8.0镜像 docker pull mysql:8.0#检查 docker images | grep mysql代码流程 由于Mysql8.0的ssl验证十分繁琐,在创建容器的时候一定要禁掉 创建自定义网络 docker network create mysql-replication-ne…...
IDEA中打开项目Vue+Vue基本语法
一、IDEA中打开项目 1.IDEA中安装Vue基本插件 2.项目结构 项目根目录 node_modules : npm 加载的项目依赖模块 public : 存放静态资源,如图片、视频等。 src : 项目源码目录,包含主要的开发文件。 index.html : 首页入口文件,可以添…...
【深度学习新浪潮】图像修复(Image Inpainting)技术综述:定义、进展与应用展望
本文为精简版,完整技术细节与参考文献可与作者讨论。 1. 图像修复的定义与核心目标 图像修复(Image Inpainting)是一种通过算法手段填补图像中缺失区域或移除不需要对象的技术,其核心目标是利用图像上下文信息生成与周围像素一致且视觉自然的内容。该技术通过计算机视觉和…...
【实战】解决图片 Hover 抖动问题的完整指南
在开发网站时,很多人都会遇到一个常见问题:鼠标移动到图片上,图片放大,结果发生抖动或闪烁。这个问题往往伴随着后端接口请求、JS 动态追加 DOM 等复杂行为。 本文将深入剖析这个问题的成因,并提供一套彻底的解决方案…...
java容器
一、List 接口实现类 1. ArrayList 特性:基于动态数组实现,支持快速随机访问(时间复杂度 O(1)),但插入/删除元素时需移动后续元素(时间复杂度 O(n)) 一、核心方法分类 添加元素 add(E e):尾部追加元素,均摊时间复杂度O(1)add(int index, E element):指定位置插入…...
arthas之jvm相关命令
文章目录 1. dashboard2. thread线程相关3. jvmTHREAD相关文件描述符相关 4. sysprop5. 小结6. sysenv7. vmoption8. getstatic9. ognl10. 小结 1. dashboard 作用:显示当前系统的实时数据面板,按q或ctrlc退出 数据说明 ID: Java级别的线程IDÿ…...
UDP视频传输中的丢包和播放花屏处理方法
在处理UDP视频传输中的丢包和花屏问题时,需要结合编码优化、网络传输策略和接收端纠错技术。以下是分步骤的解决方案: 1. 前向纠错(FEC,Forward Error Correction) 原理:在发送数据时附加冗余包,接收方通过冗余信息恢复丢失的数据包。 实现方法: 使用Reed-Solomon、XO…...
蓝桥杯 班级活动
问题描述 小明的老师准备组织一次班级活动。班上一共有 n 名同学(n 为偶数),老师想把所有同学进行分组,每两名同学一组。 为了公平,老师给每名同学随机分配了一个 n 以内的正整数作为 id,第 i 名同学的 i…...
Open webui的使用
问题 之前本地量化模型管理器ollama的文章,我们知道可以通过ollama来管理本地量化模型,也能够在命令行中与相关模型进行对话。现在我们想要在有个web页面通过浏览器来与本地模型对话。这里我们就使用Open webui作为界面来与本地模型对话。 安装启动 这…...
页面重构过程中如何保证良好的跨浏览器一致性?
在页面重构的过程中,为了确保网页能够在不同的浏览器中呈现一致的效果,我们需要采取一系列措施来提高跨浏览器的一致性。以下是几个关键步骤和技术要点: 使用标准化的HTML和CSS:始终遵循最新的Web标准编写代码,例如采用…...
Python库与Excel
目录 一、库 1、Python自带的库 2、第三方库 3、第三方库的安装 二、import的用法 三、datetime库 1、处理日期 2、处理时刻 3、局限性 四、random库 1、函数 2、随机种子 3、发牌模拟器 五、jieba库 六、openpyxl库 1、表格读取 2、表格元素遍历 3、工作表的…...
记录一下最近参与实习 外包 社招流程里的一些感悟
记录一下最近参与实习 外包 社招流程里的一些感悟 1.简历门面要重视 1.简历非常重要,它是你的门面 初步了解到你的一个实习/工作经历,然后掌握的技术栈,是否与当前项目匹配,哪些模块上的设计是我们想要重点关注的,可…...
流动的梦境:GPT-4o 的自回归图像生成深度解析
每周跟踪AI热点新闻动向和震撼发展 想要探索生成式人工智能的前沿进展吗?订阅我们的简报,深入解析最新的技术突破、实际应用案例和未来的趋势。与全球数同行一同,从行业内部的深度分析和实用指南中受益。不要错过这个机会,成为AI领…...
HarmonyOS NEXT开发进阶(十四):HarmonyOS应用开发者基础认证试题集汇总及答案解析
文章目录 一、前言二、判断题(134道)三、单选题(210道)四、多选题(123道)五、拓展阅读 一、前言 鸿蒙原生技能学习阶段,通过官方认证的资格十分有必要,在项目实战前掌握基础开发理论…...
Visual Studio Code(简称 VS Code)下载与使用教程1(新建文件,语法高亮,快捷键,主题,快捷指令)
简介 由 微软(Microsoft) 开发的 免费、开源、跨平台 的 代码编辑器,广泛用于编程开发、文本编辑和调试。 主要功能 代码编辑:支持几乎所有编程语言(Python、JavaScript、Java、C、Go 等),提供…...
3.28前端模拟面试
针对你 1.5 年的前端经验,结合 Vue 3、TypeScript、微前端(qiankun)等背景,我准备了一套模拟面试题,偏向场景化问题,考察你的实战经验和思维能力。 一、工程化 & 架构 你们的前端项目使用 qiankun 做微…...
pip 安装某个包之后,Jupyter Lab仍旧显示包冲突;例如:Numba needs NumPy 2.1 or less. Got NumPy 2.2.
异常提示 Numba needs NumPy 2.1 or less. Got NumPy 2.2. --------------------------------------------------------------------------- ImportError Traceback (most recent call last) Cell In[8], line 53 import pywt4 import matplot…...
Python:爬虫概念与分类
网络请求: https://www.baidu.com url——统一资源定位符 请求过程: 客户端,指web浏览器向服务器发送请求 请求:请求网址(request url);请求方法(request methods);请求头(request header)&…...
flask开发中设置Flask SQLAlchemy 的 db.Column 只存储非负整数(即 0 或正整数)
如果你想控制一个 Flask SQLAlchemy 的 db.Column 只存储非负整数(即 0 或正整数),你可以在模型中使用验证来确保这一点。一种常见的方法是使用模型的 validate 方法或者在执行插入或更新操作时进行检查。 以下是实现这一目标的几种方法&…...
从0到1解决项目问题经验-Vue3前端
问题1: 我有文件里面这么一段代码,但是现在有个问题,就是在设备信息详情的抽屉页面中,当我首次点击查看的时候,显示的物流中心名称现在是跟"deviceInfo.logisticsCenterName"做的绑定,于是现在显…...
Vue.js的CSS过渡与动画:常用案例解析
🤍 前端开发工程师、技术日更博主、已过CET6 🍨 阿珊和她的猫_CSDN博客专家、23年度博客之星前端领域TOP1 🕠 牛客高级专题作者、打造专栏《前端面试必备》 、《2024面试高频手撕题》、《前端求职突破计划》 🍚 蓝桥云课签约作者、…...
【论文阅读】Co2l: Contrastive continual learning
原文链接:[2106.14413] Co$^2$L: Contrastive Continual Learning 阅读本文前,需要对持续学习的基本概念以及面临的问题有大致了解,可参考综述: Wang L, Zhang X, Su H, et al. A comprehensive survey of continual learning: …...
Python给对象数组排序
文章目录 1. 使用sorted()函数(返回新的排序后的列表)2. 使用list.sort()方法(原地排序,不返回新列表)3. 如果数据结构是集合(set),集合本身是无序的,无法直接排序&#…...
Docker-清理容器空间prune
docker system prune -a 是一个非常有用的命令,用于清理 Docker 系统中未使用的资源,包括停止的容器、未使用的网络、卷以及未被任何容器引用的镜像(悬空镜像和所有未使用的镜像)。以下是关于该命令的详细说明: 命令…...
Kubernetes》》K8S》》Deployment 、Pod、Rs 、部署 nginx
Deployment deployment文档说明 kubectl get rs,deployment,pods 删除pod 、deployment 、service # 如果只删除pod,deployment会自动重建,所以应该先删除deployment。 # 下面演示的是删除所有deployment,可以指定只删除某个 # 删除所有…...
【Zookeeper搭建】Zookeeper分布式集群搭建完整指南
Zookeeper分布式集群搭建 (一)克隆前准备工作 一、时钟同步 步骤: 1、输入date命令可以查看当前系统时间,可以看到此时系统时间为PDT(部分机器或许为EST),并非中国标准时间。我们在中国地区…...
基于YOLO11/WVP的电梯系统开发-模型训练与rk3568移植
1. 环境准备 代码下载: https://github.com/ultralytics/ultralytics.git切换到 8.3.0 以上的分支,yolov11 只在上述分支支持, 下载后在 ultralytics 根目录下安装 yolo 依赖环境: pip install -e . -i https://pypi.tuna.tsinghua.edu.cn…...
[数据结构]并查集(系统整理版)
基础用法 int p[N];//路径压缩 寻找祖宗节点 int find(int x){if(p[x]!x) p[x]find(p[x]);return p[x]; }int main(){ //初始化for(int i1;i<n;i) p[i]i; }合并 void merge(int a,int b){int aafind(a),bbfind(bb);if(aa!bb){p[aa]bb;} }查询是否联通 bool is_connected(…...
人工智能与软件工程结合的发展趋势
AI与软件工程的结合正在深刻改变软件开发的流程、工具和方法,其发展方向涵盖了从代码生成到系统维护的整个生命周期。以下是主要的发展方向和技术趋势: 1. 软件架构体系的重构 从“面向过程”到“面向目标”的架构转型: AI驱动软件设计以目标…...
Compose 实践与探索十七 —— 多指手势与自定义触摸反馈
上一节我们讲了滑动的手势识别以及嵌套滑动,二者都属于触摸反馈这个大的范畴内的知识。本节我们将深入触摸反馈这个话题,讲一讲多指手势的识别与完全自定义的触摸反馈的实现。 1、多指手势 多指手势可以分为两类: 利用 API 处理预设好的手…...
哈希表 - 两个数组的交集(集合、数组) - JS
一、Set基础 在 JavaScript 中,Set 是一种集合(Collection)数据结构,用于存储唯一值(不允许重复),并且可以高效地进行添加、删除、查询等操作。它类似于数组(Array)…...
26_ajax
目录 了解 接口 前后端交互 一、安装服务器环境 nodejs ajax发起请求 渲染响应结果 get方式传递参数 post方式传递参数 封装ajax_上 封装ajax下 了解 清楚前后端交互就可以写一些后端代码了。小项目 现在写项目开发的时候都是前后端分离 之前都没有前端这个东西&a…...
Java面试黄金宝典24
1. 什么是跳表 定义 跳表(Skip List)是一种随机化的数据结构,它基于有序链表发展而来,通过在每个节点中维护多个指向其他节点的指针,以多层链表的形式组织数据。其核心思想是在链表基础上增加额外层次,每…...
每日c/c++题 备战蓝桥杯(全排列问题)
题目描述 按照字典序输出自然数 1 到 n 所有不重复的排列,即 n 的全排列,要求所产生的任一数字序列中不允许出现重复的数字。 输入格式 一个整数 n。 输出格式 由 1∼n 组成的所有不重复的数字序列,每行一个序列。 每个数字保留 5 个场…...
Layui实现table动态添加行,可删除、表格可编辑,小数校验
实现如图需求,layui实现的可编辑table,包含B、C、D、E列,A列不用实现出现,A列放在附件就是让你明白,不同的物料名称,行是不一样的。除了头部表头和E列不能编辑,每个表格都可编辑,其中…...
Spring Boot 非web应用程序
在 Spring Boot 框架中,要创建一个非Web应用程序(纯Java程序) main方法运行,不启动tomcat,main方法执行结束,程序就退出了; 方式一 1、SpringBoot开发纯Java程序,应该采…...
数据分析中的基线校正算法全解析:原理、实现与应用
数据分析中的基线校正算法全解析:原理、实现与应用 在数据分析中,基线漂移是一个常见问题,会严重影响数据的解释和分析精度。本文将详细介绍12种主流基线校正方法,包括数学原理、Python实现代码和适用场景分析。 基线漂移问题概述 基线漂移主要由以下因素引起: 仪器强度…...
国外计算机证书推荐(考证)(6 Sigma、AWS、APICS、IIA、Microsoft、Oracle、PMI、Red Hat)
文章目录 证书推荐1. 六西格玛 (6 Sigma)2. 亚马逊网络服务 (AWS)3. 美国生产与库存控制学会 (APICS)4. 内部审计师协会 (IIA)5. 微软 (Microsoft)6. 甲骨文 (Oracle)7. 项目管理协会 (PMI)8. 红帽 (Red Hat) 证书推荐 1. 六西格玛 (6 Sigma) 介绍:六西格玛是一种…...
linux》》docker 、containerd 保存镜像、打包tar、加载tar镜像
Linux》》docker: 默认情况下,Docker镜像保存在/var/lib/docker/目录下。 当您使用docker pull命令从Docker Hub或私有镜像仓库中拉取镜像时,Docker会自动将镜像文件保存在/var/lib/docker/image/目录下。 每个镜像都由一个或多个层组成,这些…...
大数据(2)Hadoop架构深度拆解:HDFS与MapReduce企业级实战与高阶调优
目录 一、分布式系统的设计哲学演进1.1 从Google三驾马车到现代数据湖 二、企业级HDFS架构全景图2.1 联邦架构的深度实践2.2 生产环境容灾设计2.3 性能压测方法论 三、MapReduce引擎内核解密3.1 Shuffle机制全链路优化3.2 资源调度革命:从MRv1到YARN3.3 企业级编码规…...
【数学建模】动态规划算法(Dynamic Programming,简称DP)详解与应用
动态规划算法详解与应用 文章目录 动态规划算法详解与应用引言动态规划的基本概念动态规划的设计步骤经典动态规划问题1. 斐波那契数列2. 背包问题3. 最长公共子序列(LCS) 动态规划的优化技巧动态规划的应用领域总结 引言 动态规划(Dynamic Programming,简称DP)是一…...
UE学习记录part11
第14节 breakable actors 147 destructible meshes a geometry collection is basically a set of static meshes that we get after we fracture a mesh. 几何体集合基本上是我们在断开网格后获得的一组静态网格。 选中要破碎的网格物品,创建集合 可以选择不同的…...
LeetCode知识点整理
1、Scanner 输入: import java.util.Scanner;public class Main {public static void main(String[] args) {Scanner scanner new Scanner(System.in);// 读取整数int num scanner.nextInt();// 读取一行字符串String line scanner.nextLine();scanner.close();…...
浅析车规芯片软错误防护加固的重要性
随着汽车电子技术的飞速发展,汽车已经从传统的机械交通工具转变为高度依赖电子系统的智能移动终端。车规芯片作为汽车电子系统的核心部件,其可靠性和安全性直接关系到车辆的正常运行和驾乘人员的安全。然而,车规芯片在复杂的运行环境中面临着…...
Android Jetpack学习总结(源码级理解)
ViewModel 和 LiveData 是 Android Jetpack 组件库中的两个核心组件,它们能帮助开发者更有效地管理 UI 相关的数据,并且能够在配置变更(如屏幕旋转)时保存和恢复 UI 数据。 ViewModel作用 瞬态数据丢失的恢复,比如横竖…...
Matlab_Simulink中导入CSV数据与仿真实现方法
前言 在Simulink仿真中,常需将外部数据(如CSV文件或MATLAB工作空间变量)作为输入信号驱动模型。本文介绍如何高效导入CSV数据至MATLAB工作空间,并通过From Workspace模块实现数据到Simulink的精确传输,适用于运动控制…...
Go 语言规范学习(6)
文章目录 StatementsTerminating statementsEmpty statementsLabeled statementsExpression statementsSend statementsIncDec statementsAssignment statementsIf statementsSwitch statementsExpression switchesType switches For statementsFor statements with single con…...
设计模式——设计模式理念
文章目录 参考:[设计模式——设计模式理念](https://mp.weixin.qq.com/s/IEduZFF6SaeAthWFFV6zKQ)参考:[设计模式——工厂方法模式](https://mp.weixin.qq.com/s/7tKIPtjvDxDJm4uFnqGsgQ)参考:[设计模式——抽象工厂模式](https://mp.weixin.…...