当前位置：首页 > news >正文

12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档)

news 来源：原创 2025/5/17 21:25:53

12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档)

SpringDoc OpenAPI 是一个基于 OpenAPI 3.0/3.1 规范的工具，用于为 Spring Boot 应用生成 API 文档。它是 springfox（Swagger 2.x）的现代替代方案，完全支持 Spring Boot 3.x 和 JDK 17+，具有更强的兼容性和功能。

1. SpringDoc OpenAPI 核心概念

(1) OpenAPI 规范

OpenAPI（原 Swagger 规范）是描述 RESTful API 的行业标准，支持 API 文档、测试和客户端代码生成。
SpringDoc OpenAPI 自动将 Spring Boot 的控制器、模型等转换为 OpenAPI 格式，并生成交互式 UI（Swagger UI）。

(2) 与 Spring Boot 的集成

自动扫描：无需手动配置，SpringDoc 会自动扫描 @RestController、@RequestMapping 等注解的 API。
注解支持：通过 @Operation、@Tag 等注解丰富文档内容。
支持现代技术栈：兼容 WebFlux、Kotlin、Jakarta EE 9+ 等。

(3) 关键组件

OpenAPI 对象：定义 API 的元信息（标题、描述、版本等）。
@Tag 注解：对 API 进行分类（如用户管理、订单管理）。
@Operation 注解：描述单个 API 操作（如 GET、POST）。
@Schema 注解：描述模型类的字段（如用户 ID、用户名）。

2. SpringDoc OpenAPI 核心知识点

(1) 依赖与版本

Maven 依赖：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version> <!-- 最新稳定版 -->
</dependency>

版本选择：
- 2.x 系列支持 Spring Boot 3.x 和 OpenAPI 3.0。
- 如果需要 OpenAPI 3.1，可以使用 springdoc-openapi-starter-webmvc-api。

(2) 配置方式

自动配置：
- 默认配置下，SpringDoc 会自动生成 API 文档，无需额外代码。
自定义配置：
- 通过 OpenAPI 对象自定义元信息（如标题、描述）。
- 通过 @Tag 和 @Operation 注解补充 API 细节。

(3) 常用注解

注解	作用
`@Tag`	对 API 进行分类（如 `@Tag(name = "用户管理")`）。
`@Operation`	描述单个 API 操作（如 `@Operation(summary = "获取用户")`）。
`@Schema`	描述模型类的字段（如 `@Schema(description = "用户ID")`）。
`@Parameter`	描述请求参数（如 `@Parameter(description = "用户ID")`）。
`@ApiResponse`	描述响应状态码和内容（如 `@ApiResponse(responseCode = "200")`）。

(4) 执行路径

Swagger UI 路径：

默认访问：http://localhost:8080/swagger-ui.html。

可通过配置修改路径：

@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/public/**").build();
}

OpenAPI JSON 路径：
- 默认访问：http://localhost:8080/v3/api-docs。
- 支持分组 API 的 JSON 路径（如 /v3/api-docs/public）。

3. SpringDoc OpenAPI 的工作流程

启动应用：
- SpringDoc 自动扫描所有 @RestController 和 @RequestMapping 注解的 API。
生成文档：
- 根据控制器、模型和注解生成 OpenAPI 3.0/3.1 格式的 JSON。
渲染 UI：
- 通过 Swagger UI 渲染交互式文档，支持测试 API。

4. 高级功能

(1) 分组 API

将 API 按功能分组（如公共 API、管理员 API）：

@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public").pathsToMatch("/public/**").build();
}

访问分组后的 Swagger UI：
- http://localhost:8080/swagger-ui/index.html#/public

(2) 安全性集成

如果项目启用了 Spring Security，需要允许访问 Swagger UI：

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/swagger-ui.html", "/v3/api-docs/**").permitAll().anyRequest().authenticated();}
}

(3) 自定义 UI 配置

修改 Swagger UI 的标题、布局等：

@Bean
public UIConfiguration uiConfig() {return UIConfiguration.builder().deepLinking(true).displayOperationId(false).docExpansion(DocExpansion.NONE).build();
}

(4) 支持 OpenAPI 3.1

使用 springdoc-openapi-starter-webmvc-api 依赖：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-api</artifactId><version>2.3.0</version>
</dependency>

5. 与 Spring Boot 3.x 的兼容性

为什么不用 springfox？
- springfox（Swagger 2.x）依赖了已移除的 Spring MVC 组件（如 PathPatternParser），无法与 Spring Boot 3.x 兼容。
- SpringDoc OpenAPI 是专门为 Spring Boot 3.x 和 Jakarta EE 9+ 设计的。

6. 总结

优势：
- 完全兼容 Spring Boot 3.x 和 JDK 17+。
- 支持 OpenAPI 3.0/3.1，功能更强大。
- 无需手动配置，自动扫描 API。
适用场景：
- 需要快速生成 API 文档的 Spring Boot 项目。
- 需要支持 OpenAPI 3.0/3.1 的现代应用。
对比 springfox：
- SpringDoc 是 springfox 的替代方案，推荐在新项目中使用。

通过 SpringDoc OpenAPI，可以轻松为 Spring Boot 应用生成高质量的 API 文档，并支持交互式测试。

12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档)

12.SpringDoc OpenAPI 功能介绍(用于生成API接口文档) SpringDoc OpenAPI 是一个基于 OpenAPI 3.0/3.1 规范的工具，用于为 Spring Boot 应用生成 API 文档。它是 springfox（Swagger 2.x）的现代替代方案，完全支持 Spring Boot 3.x…...

编程日记 2025/5/17 21:25:53

Java 实用时间工具类：DateUtils 与 DurationFormatUtils

前言在 Java 项目中，处理日期时间相关的操作极为常见。Apache Commons Lang 提供了两个非常实用的时间工具类：DateUtils 和 DurationFormatUtils，它们分别负责简化日期处理和格式化时间间隔，帮助开发者更高效地进行时间操作。一…...

编程日记 2025/5/3 19:25:35

Unity3D仿星露谷物语开发40之割草动画

1、目标当Player选择Scythe后，鼠标悬浮在草上，会显示绿色光标。鼠标左击，会触发割草的动画。 2、优化Settings.cs脚本添加以下两行代码： // Reaping（收割） public const int maxCollidersToTestPerRe…...

编程日记 2025/5/14 16:53:42

量化交易之数学与统计学基础2.4——线性代数与矩阵运算 | 矩阵分解

量化交易之数学与统计学基础2.4——线性代数与矩阵运算 | 矩阵分解第二部分：线性代数与矩阵运算第4节：矩阵分解：奇异值分解（SVD）在数据压缩和风险分解的应用一、奇异值分解（SVD）基础&#xf…...

编程日记 2025/5/1 5:35:28

ES使用之查询方式

文章目录 ES中的数据查询返回字段含义track_total_hits 精准匹配(term)单值匹配多值匹配全文检索(match)range查询高级查询布尔查询 ES中的数据查询返回字段含义 track_total_hits track_total_hits是 Elasticsearch 中用于 ‌控制匹配文档总数统计行为‌ 的关键参数。就算…...

编程日记 2025/5/15 7:24:11

力扣-数组-41缺失的第一个正数

思路关键有两点原地哈希把1-len的数分别映射到下标为0 - len-1的地方中交换后，接着查看下标i被交换过来的数，直到他到了该到的位置或者超出范围使用while，把不满足映射关系的点一直交换，直到下标指向的位置符合要求代…...

编程日记 2025/5/1 5:34:26

Nginx — http、server、location模块下配置相同策略优先级问题

一、配置优先级简述在 Nginx 中，http、server、location 模块下配置相同策略时是存在优先级的，一般遵循 “范围越小，优先级越高” 的原则，下面为你详细介绍： 1. 配置继承关系 http 块：作为全局配置块&…...

编程日记 2025/5/16 9:36:14

管家婆易指开单如何设置零售开单

一，零售设置 1，登录管理员账号-基本信息--职员信息-新建职员及其属于哪个门店。 2，系统维护-系统管理-用户配置-系统配置-切换为“触摸屏模式或者普通零售模式” 3，用户及权限设置-给该员工开通零售及开单等相关的权限 4&#xff…...

编程日记 2025/5/1 5:34:24

深入浅出循环神经网络（RNN）：原理、应用与实战

1、引言在深度学习领域，循环神经网络（Recurrent Neural Network, RNN）是一种专门用于处理**序列数据**的神经网络架构。与传统的前馈神经网络不同，RNN 具有**记忆能力**，能够捕捉数据中的时间依赖性，广泛应…...

编程日记 2025/5/5 7:10:04

【Java】打印运行环境中某个类引用的jar版本路径

背景正式环境出现jar版本不匹配问题，不知道正式环境用的哪个jar版本。通过一下可以打印出类调用的jar // 获取 POIFSFileSystem 类的加载器并打印其来源路径 ClassLoader classloaderPOIFS org.apache.poi.poifs.filesystem.POIFSFileSystem.class.getClassLoade…...

编程日记 2025/5/14 20:40:12

【效率提升】Vibe Coding时代如何正确使用输入法：自定义短语实现Prompt快捷输入

AI时代的效率神器：用搜狗拼音自定义短语实现Prompt快捷输入在日益依赖AI工具的今天，我们经常需要输入各种复杂的prompt来指导AI完成特定任务。有些同学完全忽视了这一层工作的意义，实际上不同质量的prompt对模型的表现影响是巨大的。&#…...

编程日记 2025/5/1 5:33:21

C# 类的基本概念(从类的内部访问成员和从类的外部访问成员)

本章内容： 类的概述程序和类：一个简单的示例声明类类成员创建变量和类的实例为数据分配内存实例成员访问修饰符从类的内部访问成员从类的外部访问成员综合应用从类的内部访问成员如前所述，类的成员仅用其他类成员的名称就可以访…...

编程日记 2025/5/11 22:48:46

端到端观测分析：从前端负载均衡到后端服务

前言我们在做系统运维保障的时候，关注从前端负载均衡到后端服务的流量情况是很有必要的，可以了解每个后端服务实例接收的流量大小，这有助于确定资源分配是否合理，能够帮助找出后端服务中的性能瓶颈。同时，当系统出现…...

编程日记 2025/5/1 5:32:18

Axure疑难杂症：全局变量跨页面赋值、中继器交互（玩转全局变量）

亲爱的小伙伴，在您浏览之前，烦请关注一下，在此深表感谢！ Axure产品经理精品视频课已登录CSDN可点击学习https://edu.csdn.net/course/detail/40420 课程主题：全局变量高级交互主要内容：数据跨页面传递、赋值、中继器交互应用场景：页面间值的传递、赋值案例展示：…...

编程日记 2025/5/1 5:32:17

css 数字从0开始增加的动画效果

项目场景： 提示：这里简述项目相关背景： 在有些时候比如在做C端项目的时候，页面一般需要一些炫酷效果，比如数字会从小值自动加到数据返回的值 css 数字从0开始增加的动画效果分析： 提示：这里填…...

编程日记 2025/5/16 9:52:57

【MongoDB篇】MongoDB的索引操作！

目录引言第一节：天生的“索引小能手”——_id 索引 🆔第二节：自己动手，丰衣足食——创建索引 🔑🛠️第三节：索引的“类型”——因“材”施“索”！🌳🔑第四节…...

编程日记 2025/5/1 5:32:15

写劳动节前的跨系统文件传输

功能说明： 协议隐身：流量伪装为HTTPS图片传输动态混淆：每个数据包添加随机填充军用级擦除：临时文件三次覆写清除抗分析：随机传输时间间隔和端口跳跃隐蔽通道：ALTSHIFTC触发隐藏控制台网络架构建…...

编程日记 2025/5/1 5:32:14

腾讯元宝桌面客户端：基于Tauri的开源技术解析

2025年3月，腾讯元宝宣布上线电脑客户端版本，支持Windows和macOS系统。作为腾讯旗下的AI助手产品，腾讯元宝桌面端采用了Tauri而非传统的Electron作为其跨平台开发框架，这一技术选择体现了腾讯对应用性能、安全性和用户体验的重视。本文将依据腾讯元宝桌面客户端的用户规则中…...

编程日记 2025/5/1 5:32:13

重塑驾乘体验！哈曼Ready系列引爆「人车交互革命」

AI定义汽车趋势下，AI加速赋能整车辅助驾驶、智能座舱、智能底盘等各域。以智能座舱为例，AI大模型的快速应用与迭代，推动智能座舱加速迈入“多模交互”阶段，融合视觉、听觉、触觉等感知技术，智能座舱向着终极形态演进…...

编程日记 2025/5/17 12:32:19

第二章-科学计算库NumPy

第二章-科学计算库NumPy Numpy 作为高性能科学计算和数据分析的基础包,是其他重要数据分析工具的基础, 掌握 NumPy 的功能及其用法, 将有助于后续其他数据分析工具的学习. 2.1 认识 NumPy 数组对象 NumPy 中最重要的一个特点就是其 N 维数组对象, 即 ndarray(别名 array) 对象…...

编程日记 2025/5/14 8:20:04

3.2goweb框架GORM

GORM 是 Go 语言中功能强大的 ORM（对象关系映射）框架，支持 MySQL、PostgreSQL、SQLite、SQL Server 等主流数据库。以下是 GORM 的核心概念和用法详解： 一、基础入门 1. 安装 go get -u gorm.io/gorm go get -u gorm.io…...

编程日记 2025/5/1 5:31:11

KUKA机器人不同的用户权限详细介绍

对于KUKA机器人，主菜单里有一个“用户组”的登录，不同的用户组对应不同的权限。一、KUKA示教器正常开机后显示以下界面，对于8.5及以上的系统，增加了快捷登录用户组的符号 ，直接点击即可打开。在 smartHMI 上&…...

编程日记 2025/5/1 5:31:10

AI对IT行业的重塑：挑战与机遇并存的技术革命

一、必要性：AI成为IT行业的基础设施在云计算、大数据和物联网构成的数字生态中，AI技术已成为IT行业的"水电煤"。以微软Azure为例，其AI云服务支撑着全球超过85%的《财富》500强企业，通过机器学习模型自动优化服务器集群…...

编程日记 2025/5/1 5:31:10

利用IEEE异常机制优化Fortran浮点数计算

利用IEEE异常机制优化Fortran浮点数计算在Fortran程序中，IEEE浮点异常机制可以帮助你检测和优化浮点数计算，提高数值稳定性和程序健壮性。以下是几种利用IEEE异常机制优化浮点数计算的方法： 1. 启用和检测IEEE异常现代Fortran&#xff0…...

编程日记 2025/5/7 8:30:54

构建网页版IPFS去中心化网盘

前言：我把它命名为无限网盘 Unlimited network disks（ULND），可以实现简单的去中心化存储，其实实现起来并不难，还是依靠强大的IPFS，跟着我一步一步做就可以了。第一步：准备开发环境…...

编程日记 2025/5/16 9:24:03

【solidity基础】一文说清楚合约函数的大小事

在 Solidity 里，函数是合约的关键构成部分，用于执行特定任务或操作的代码块，可以包含逻辑、访问状态变量、进行计算，并且可以接受参数和返回值。但是solidity 的函数与其他语言不太一样，经常会有同学搞混，这里开一篇文章完整介绍一下 solidity 函数的用法。 1. 函数定…...

编程日记 2025/5/1 5:31:08

用Python构建自动驾驶传感器融合算法：从理论到实践

用Python构建自动驾驶传感器融合算法：从理论到实践随着自动驾驶技术的飞速发展，传感器在自动驾驶系统中的作用愈发重要。传感器不仅是车辆感知外部环境的“眼睛”，它们提供的信息也是自动驾驶决策系统的基础。然而，单一传感器的感知能力是有限的。为了提升自动驾驶系统的…...

编程日记 2025/5/13 21:39:41

PLC与工业电脑：有什么区别？

随着工业部门的快速发展，自动化已经从奢侈品转变为绝对必需品。世界各地的工业越来越多地采用工业自动化来提高效率、提高精度并最大限度地减少停机时间。这场自动化革命的核心是两项关键技术：可编程逻辑控制器（PLC）和电脑&#x…...

编程日记 2025/5/1 5:30:06

机器学习：在虚拟环境中使用 Jupyter Lab

机器学习：在虚拟环境中使用 Jupyter Lab 第一步：激活虚拟环境打开终端（CMD/PowerShell）并执行： $cmd #激活虚拟环境 $conda activate D:\conda_envs\mll_env 激活后，终端提示符前会显示环境名称&…...

编程日记 2025/5/1 5:30:05

Arduino项目实战与编程技术详解

一、智能避障小车：超声波传感器与PWM电机控制 1.1 硬件需求与工作原理智能避障小车的核心在于超声波传感器与电机驱动模块的协同工作。超声波传感器（HC-SR04）通过发射高频声波并接收回波来测量距离，而L298N电机驱动模块则负责控制两个直流电机的转向与速度。 1.1.1 超声…...

编程日记 2025/5/1 5:30:04

AI数字人：人类身份与意识的终极思考（10/10）

文章摘要：AI数字人技术正在引发从"像素复刻"到"意识投射"的范式革命，多模态交互、神经辐射场等技术突破推动数字人从工具属性迈向虚拟主体。其发展伴随身份认同危机、伦理困境，促使人类重新思考自我认知与"人之为人…...

编程日记 2025/5/14 8:29:55

【单例模式】简介

目录概念理解使用场景优缺点实现方式概念理解单例模式要保证一个类在整个系统运行期间，无论创建多少次该类的对象，始终只会有一个实例存在。就像操作系统中的任务管理器，无论何时何地调用它，都是同一个任务管理器在工作&#…...

编程日记 2025/5/1 5:30:02

安凯微以创新之芯，赋能万物智能互联新时代

在全球半导体产业步入深度调整期的当下，安凯微用一份“技术浓度”远超“财务数字”的年报，向市场传递出其作为物联网智能硬件核心SoC芯片领军者的战略定力。面对行业短期波动，公司选择以技术纵深突破与生态价值重构为锚点，在逆势中…...

编程日记 2025/5/16 9:13:58

TIME_WAIT状态+UDP概念及模拟实现服务器和客户端收发数据

目录一、TIME_WAIT状态存在的原因二、TIME_WAIT状态存在的意义三、TIME_WAIT状态的作用四、UDP的基本概念 4.1 概念 4.2 特点五、模拟实现UDP服务器和客户端收发数据 5.1 服务器udpser 5.2 客户端udpcil 一、TIME_WAIT状态存在的原因 1.可靠的终止TCP连接。 2.…...

编程日记 2025/5/1 5:30:00

高并发内存池（五）：性能测试与性能优化

前言在前几期的实现中，我们完成了tcmalloc基础的内存管理功能，但还存在两个关键问题： 未处理超过256KB的大内存申请。前期测试覆盖不足，导致多线程场景下隐藏了一些bug。本文将修复这些问题，并实现三个目标&…...

编程日记 2025/5/1 5:28:59

景联文科技牵头起草的《信息技术可扩展的生物特征识别数据交换格式第4部分：指纹图像数据》国家标准正式发布

2025年3月28日，由景联文科技作为第一起草单位主导编制的国家标准GB/T 45284.4-2025 《信息技术可扩展的生物特征识别数据交换格式第4部分：指纹图像数据》正式获批发布，将于2025年10月1日开始实施。该标准的制定标志着我国生物特征识别领域标…...

编程日记 2025/5/16 16:52:34

完美解决 mobile-ffmpeg Not overwriting - exiting

在使用ffmpeg库 ，有pcm转换到 aac的过程中报错 mobile-ffmpeg Not overwriting - exiting终于在网上翻到，在output 输出文件的地方加 -y, 重复覆盖的意思，完美解决。...

编程日记 2025/5/1 5:28:58

4：QT联合HALCON编程—机器人二次程序抓取开发（九点标定）

判断文件是否存在 //判断文件在不在 int HandEyeCalib::AnsysFileExists(QString FileAddr) {QFile File1(FileAddr);if(!File1.exists()){QMessageBox::warning(this,QString::fromLocal8Bit("提示"),FileAddrQString::fromLocal8Bit("文件不存在"));retu…...

编程日记 2025/5/1 5:27:57

C语言之操作符

目录 1. 操作符的分类 2. 移位操作符 2.1 左移操作符 << 2.2 右移操作符 >> 3. 位操作符 3.1 按位与 & 3.2 按位或 | 3.3 按位异或 ^ 3.4 按位取反 ~ 3.5 例题 3.5.1 按位异或 ^ 拓展公式 3.5.2 不能创建临时变量（第三个变量&#xff…...

编程日记 2025/5/1 5:27:56

【优选算法 | 前缀和】前缀和算法：高效解决区间求和问题的关键

算法相关知识点可以通过点击以下链接进行学习一起加油！双指针滑动窗口二分查找在本篇文章中，我们将深入解析前缀和算法的原理。从基础概念到实际应用，带你了解如何通过前缀和高效解决数组求和、区间查询等问题。无论你是刚接触算法的新手&am…...

编程日记 2025/5/1 5:27:55

『深夜_MySQL』详解数据库探索数据库是如何存储的

1. 数据库基础 1.1 什么是数据库存储数据用文件就可以了，那为什么还要弄个数据库？ 一般的文件缺失提供了数据的存储功能，但是文件并没有提供非常好的数据管理能力（用户角度，内容方面） 文件保存数据有以…...

编程日记 2025/5/1 5:27:55

Microsoft Entra ID 免费版管理云资源详解

Microsoft Entra ID（原 Azure AD）免费版为企业提供了基础的身份管理功能，适合小型团队或预算有限的组织。以下从功能解析到实战配置，全面展示如何利用免费版高效管理云资源。 1. 免费版核心功能与限制 1.1 功能概览功能免费版支持情况基础用户与组管理✔️ 支持创建、删除…...

编程日记 2025/5/1 5:27:54

k8s -hpa

hpa定义弹性自动伸缩 1、横向伸缩，当定义的cpu、mem指标达到hpa值时，会触发pods伸展 2、安装metrics-server 收集pods的cpu。mem信息供hpa参照安装helm curl -fsSl -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 用helm安装metr…...

编程日记 2025/5/1 5:27:54

Web应用开发指南

一、引言随着互联网的迅猛发展，Web应用已深度融入日常生活的各个方面。为满足用户对性能、交互与可维护性的日益增长的需求，开发者需要一整套高效、系统化的解决方案。在此背景下，前端框架应运而生。不同于仅提供UI组件的工具库&#xff0c…...

编程日记 2025/5/1 5:27:53

Vue3 + TypeScript 实现 PC 端鼠标横向拖动滚动

功能说明拖动功能： 鼠标按下时记录初始位置和滚动位置拖动过程中计算移动距离并更新滚动位置松开鼠标后根据速度实现惯性滚动滚动控制： 支持鼠标滚轮横向滚动（通过 wheel 事件）自动边界检测防止滚动超出内容…...

编程日记 2025/5/1 5:27:53

MyBatis的SQL映射文件中，`#`和`$`符号的区别

在MyBatis的SQL映射文件中，#和$符号用于处理SQL语句中的参数替换，但它们的工作方式和使用场景有所不同。 #{} 符号预编译参数：#{} 被用来作为预编译SQL语句的占位符。这意味着MyBatis会将你传入的参数设置为PreparedStatement的参数，从而防止SQL注入攻击，并允许MyBatis对…...

编程日记 2025/5/1 5:26:51