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

Springboot 整合 Swagger3(springdoc-openapi)

使用springdoc-openapi这个库来生成swagger的api文档

官方Github仓库: https://github.com/springdoc/springdoc-openapi

官网地址:https://springdoc.org

目录题

  • 1. 引入依赖
  • 2. 拦截器设置
  • 3. 访问接口页面
    • 3.1 添加配置项,使得访问路径变短(非必须)
  • 4. 修改页面显示信息
  • 5. 注解

1. 引入依赖

目前最新的版本是 springdoc-openapi v2.6.0。

然而 springdoc-openapi v1.8.0 是支持 Spring Boot 2.x 和 1.x 的最新开源版本。

在这里插入图片描述

而我的项目用的是 springboot 2.2.1 ,于是我就选择 1.8.0 的版本。

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.8.0</version>
</dependency>

大伙如果用的是 springboot 3 ,可以尝试使用最新版本的。

注意:SpringDoc不兼容swagger2的注解

2. 拦截器设置

如果项目中使用到了拦截器,那么就无法访问 http://localhost:8080/swagger-ui.html(端口号自行修改)

需要到 WebConfigurer 的 addInterceptors 方法中,排除swagger的路径

.excludePathPatterns("/swagger**/**","/**/api-docs/**")或者这种写法.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/**/api-docs/**")

案例:

	// 自定义拦截器JwtInterceptor,设置拦截规则@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(loginInterceptor).addPathPatterns("/**").excludePathPatterns("/login", "/register", "/files/**","/swagger**/**","/**/api-docs/**");}

或者这样写

	// 自定义拦截器JwtInterceptor,设置拦截规则@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(jwtInterceptor).addPathPatterns("/**").excludePathPatterns("/login").excludePathPatterns("/register").excludePathPatterns("/files/**")// 排除swagger.excludePathPatterns("/swagger**/**").excludePathPatterns("/**/api-docs/**");}

3. 访问接口页面

配置好拦截器,重新启动,访问 http://localhost:8080/swagger-ui.html(端口号自行修改)

就可以看到如下画面,代表可以成功使用swagger了。

在这里插入图片描述

通过搜索框可以看到,访问路径是被重定向到 http://localhost:8080/v3/api-docs

所以排除的路径中,把包含swagger和api-docs的路径都排除了。

3.1 添加配置项,使得访问路径变短(非必须)

此时也可以在application.properties中添加一些配置,具体可以参考Spring Boot 整合 springdoc-openapi中的配置。

只加一行把/swagger-ui.html这个默认路径修改成比较方便访问的路径。

springdoc.swagger-ui.path=/api-docs

这样就变成了可以用 http://localhost:8080/api-docs 较短的路径来访问了。

4. 修改页面显示信息

基本信息注解描述可用于属性
@OpenAPIDefinition定义整个 API 文档的基本信息类、接口
  • info:指定 @Info 注解的对象,用于描述 API 文档的基本信息。
@Info定义 API 文档的基本信息类、接口
  • title:API 的标题。
  • description:API 的描述。
  • version:API 的版本号。
  • termsOfService:服务条款的 URL。
  • contact:指定 @Contact 注解的对象,用于描述联系人信息。
  • license:指定 @License 注解的对象,用于描述许可证信息。
@Contact定义 API 文档中的联系人信息类、接口
  • name:联系人的名称。
  • url:联系人的网址。
  • email:联系人的电子邮件地址。
@License定义 API 文档中的许可证信息类、接口
  • name:许可证的名称。
  • url:许可证的网址。
@externalDocs定义 API 文档中的额外信息类、接口
  • description:信息的描述。
  • url:信息的网址。

同样是在WebConfigurer中配置,添加如下代码:

	@Beanpublic OpenAPI openAPI(@Value("${springdoc.version}") String appVersion) {return new OpenAPI().info(new Info()                                          // ## API的基本信息,包括标题、版本号、描述、联系人等.title("博客论坛系统 API")                             // Api接口文档标题(必填).description("博客论坛系统 前台用户和后台管理 API")      // Api接口文档描述.version(appVersion)                                  // Api接口版本.license(new License()                            // ## 联系人信息.name("Apache2.0")                            // 授权名称.url("http://springdoc.org"))                 // 授权信息).contact(new Contact()                            // ## 作者信息.name("奇妙方程式")                            // 作者名称.email("229600398@qq.com")                    // 作者邮箱.url("https://blog.csdn.net/weixin_45940369") // 介绍作者的URL地址).externalDocs(new ExternalDocumentation()                 // ## API的额外信息.description("文档")                                  // 描述.url("https://blog.csdn.net/weixin_45940369/article/details/141058944")); // 链接}

这里配置了一个自定义的配置参数springdoc.version(也可以直接写成1.0),所以需要把这个加到application.properties中

springdoc.version=1.0

重新启动,查看页面

在这里插入图片描述

5. 注解

swagger2 和 swagger3 的注解的区别

用途swagger2swagger3注解位置案例
给 API 分组@Api@Tag(name)Controller类上@Tag(name = “活动管理”)
描述 API 的操作@ApiOperation@Operation(summary)Controller方法上@Operation(summary = “新增活动接口”,
description = “新增活动接口的说明”)
描述操作的输入参数@ApiImplicitParams@ParametersController方法上
描述操作的输入参数@ApiImplicitParam@Parameter(description)Controller方法上
描述操作的输入参数@ApiParam@Parameter(description)Controller方法参数类上
描述操作的输入参数@ApiIgnore@Parameter(hidden=true) 或
@Operation(hidden=true) 或
@Hidden
类或方法或参数上
描述数据模型的属性@ApiModel@Schema实体类上@Schema(title=“活动对象”,
description=“活动对象的全部字段属性”)
描述数据模型的属性@ApiModelProperty@Schema实体类属性上@Schema(description = “活动id”,
requiredMode = Schema.RequiredMode.REQUIRED,
example = “1”)
  • title、name:名称
  • description:描述
  • requiredMode:指定该属性的必需性
    Schema.RequiredMode.REQUIRED 表示这个属性是必需
  • example:提供该属性的示例值
    展示该属性的一个具体示例

参考文章
https://www.cnblogs.com/antLaddie/p/17418078.html
https://www.cnblogs.com/strongmore/p/18106597
https://www.jianshu.com/p/0c09b675c2d3
https://blog.csdn.net/weixin_59383491/article/details/135105646

相关文章:

Springboot 整合 Swagger3(springdoc-openapi)

使用springdoc-openapi这个库来生成swagger的api文档 官方Github仓库&#xff1a; https://github.com/springdoc/springdoc-openapi 官网地址&#xff1a;https://springdoc.org 目录题 1. 引入依赖2. 拦截器设置3. 访问接口页面3.1 添加配置项&#xff0c;使得访问路径变短…...

netty4报错:io.netty.util.IllegalReferenceCountException: refCnt: 0, decrement: 1

背景&#xff1a;netty执行链中有一串自定义的handler&#xff0c;目前我想要在中间再加上一个pingPonghandler来进行控制帧的处理&#xff0c;从而避免ng的读写超时&#xff08;客户要求&#xff0c;与他们建立的通道一直连接&#xff0c;不进行断连&#xff0c;从而需要考虑n…...

2022年汽车软件行业产业细分及发展趋势分析

2022年汽车软件行业产业细分及发展趋势分析 连接 2022年汽车软件行业产业细分及发展趋势分析...

如何通过变更让 PostgreSQL 翻车

在开发应用程序和维护其后台数据库集群的过程中&#xff0c;我们经常会遇到实践与理论、开发环境与生产环境之间的差异。其中一个典型的例子就是变更数据库中的列类型。 对于在 PostgreSQL&#xff08;及其他符合 SQL 标准的系统&#xff09;中变更列类型的常规操作&#xff0…...

MySQL表涉及规范

MySQL表设计规范是为了确保数据库表结构的合理性、可读性和可维护性。以下是一些建议和规范&#xff1a; 1.使用InnoDB存储引擎&#xff1a;InnoDB存储引擎提供了事务支持、行级锁定和外键约束&#xff0c;有助于提高数据的完整性和性能。 2.表名和字段名命名规范&#xff1a…...

服务器Ubuntu22.04系统 使用dcocker部署安装ollama和搭配open_webui使用

服务器Ubuntu22.04系统 使用dcocker部署安装ollama和搭配open_webui使用 一、ubuntu和docker基本环境配置 1.更新包列表&#xff1a; 打开终端&#xff0c;输入以下命令&#xff1a; sudo apt-get updatesudo apt upgrade更新时间较长&#xff0c;请耐心等待 2. 安装docke…...

代理模式Proxy

一、代理模式&#xff08;Proxy&#xff09; 1.代理模式的定义 代理模式给某一个对象提供一个代理对象&#xff0c;并由代理对象控制对真实对象的访问&#xff0c;起到对代理对象已有功能的增强 通俗的来讲代理模式就是我们生活中常见的中介。 2.作用 中介隔离作用&#x…...

C++ 设计模式——抽象工厂模式

抽象工厂模式 抽象工厂模式 抽象工厂模式主要组成部分代码实现抽象工厂模式模式的 UML 图抽象工厂模式 UML 图解析优点和缺点适用场景 抽象工厂模式提供一个接口&#xff0c;用于创建一系列相关或相互依赖的对象&#xff0c;而无需指定它们的具体类。它通常用于需要创建多个产品…...

《亿级流量系统架构设计与实战》第十一章 Timeline Feed服务

Timeline Feed服务 一、概述1、分类2、功能 二、设计原理1、拉模式与用户发件箱2、推模式与用户收件箱3、推拉模式结合 三、关键技术1、内容与用户收件箱的交互&#xff08;推模式&#xff09;2、推送拆分子任务3、收件箱模型设计 内容总结自《亿级流量系统架构设计与实战》 一…...

氙灯老化试验箱试验机

氙灯老化试验箱&#xff0c;采用6.5KW大功率的精密水冷式氙灯&#xff0c;曝晒面积达到了6500cm2 功能强大&#xff0c;测试结果可靠 ◆ 满足国内外所有氙灯测试标准要求。 ◆ 采用氙灯灯管及滤光器组件&#xff0c;保证试验数据的可比性和重现性。 ◆ 自动旋转式三层鼓型样板架…...

【Qt】常用控件QRadioButton

常用控件QRadioButton QRadioButton是单选按钮&#xff0c;可以在多个选项中选择一个。 作为QAbstractButton和QWidget的子类&#xff0c;其属性和用法&#xff0c;对于QRadioButton同样适用。 属性说明 checkable 是否能选中 checked 是否已经被选中. checkable 是 checked…...

Mysql 离线版下载安装-(详细版)

Mysql 离线版下载安装-(详细版) 文章目录 Mysql 离线版下载安装-(详细版)1.0 下载地址2.0 解压到本地2.0.1 配置环境变量2.0.2 新建mysql配置文件ini2.0.3使用管理员启动 cmd 3.0 初始化密码忘记了4.0 修改初始化密码5.0 使用可视化工具登录Mysql 1.0 下载地址 地址&#xff1…...

Spring Boot和OCR构建车牌识别系统

​ 博客主页: 南来_北往 系列专栏&#xff1a;Spring Boot实战 OCR介绍 OCR&#xff08;Optical Character Recognition&#xff09;是光学字符识别技术的缩写&#xff0c;它能够将图像中的文本转换为机器可读和编辑的数字文本格式。这种技术广泛应用于数据输入、文档管理…...

Java-自定义注解中成员变量是Class<?>

在Java中,自定义注解可以包含各种类型的成员变量,包括 Class<?> 类型。这种类型的成员变量 通常用于表示某个类的类型信息。下面我将详细介绍如何定义一个包含 Class<?> 类型成员变量的 自定义注解,并给出一些示例代码。 1. 定义自定义注解 定义一个自定义…...

SX_UNIX套接字通信_15

UNIX套接字通信的优势&#xff1a; UNIX套接字通信常用于一个项目中的进程之间通信&#xff0c;UNIX提供了与网络套接字相似的特性&#xff0c;但是避免了网络延迟&#xff0c;提高了性能&#xff0c;但是它只能在同一台机器上使用&#xff0c;无法跨越网络的进程间通信 实例&…...

JS模块化总结 | CommonJS、ES6

BV13W42197jR 个人笔记 目录 JS模块化基础知识1. 概述1.1 什么是模块化1.2 为什么需要模块化? 2 模块化规范3 导入&导出4 CommonJS规范4.1 初步体验4.2 导出数据4.3 导入数据4.4 扩展理解4.5 浏览器端运行 5 ES6模块化规范5.1 初步体验5.2 Node中运行ES65.3 导出数据①分别…...

25考研计算机组成原理复习·3.5高速缓冲存储器

高速缓冲存储器Cache 工作原理&#xff1a;将某些主存块复制到Cache中&#xff0c;缓和CPU与主存之间的速度矛盾局部性原理 时间局部性&#xff1a;现在访问的地址&#xff0c;不久之后也很可能被再次访问空间局部性&#xff1a;现在访问的地址&#xff0c;其附近的地址也很可…...

餐厅管理系统

目录 一、 系统简介 1.1需求分析 1.2 编程环境与工具 二、 系统总体设计 2.1 系统的功能模块图。 2.2 各功能模块简介。 三、 主要业务流程 &#xff08;1&#xff09;用户及管理员登录流程图 &#xff08;2&#xff09;信息添加流程 &#xff08;3&#xf…...

杭州百腾教育科技 TiDB 6.5 to 7.5 升级记录

作者&#xff1a; reAsOn2010 原文来源&#xff1a; https://tidb.net/blog/612103f3 背景 使用 TiDB 作为我们的全量数据库已经有六七年了&#xff0c;当时还是 2.0 版本。早期TiDB的迭代和新特性的发布对于实际使用的影响还是很大的&#xff0c;所以从那个时候开始就有每…...

Redis的缓存穿透、击穿、雪崩

目录 缓存穿透 定义&#xff1a; 解决方法&#xff1a; 缓存击穿 定义&#xff1a; 解决方案&#xff1a; 缓存雪崩 定义&#xff1a; 解决方案&#xff1a; 缓存穿透、缓存击穿和缓存雪崩的区别 缓存穿透 定义&#xff1a; 查询一个不存在的数据&#xff0c;数据库未…...

Android Wi-Fi 连接失败日志分析

1. Android wifi 关键日志总结 (1) Wi-Fi 断开 (CTRL-EVENT-DISCONNECTED reason3) 日志相关部分&#xff1a; 06-05 10:48:40.987 943 943 I wpa_supplicant: wlan0: CTRL-EVENT-DISCONNECTED bssid44:9b:c1:57:a8:90 reason3 locally_generated1解析&#xff1a; CTR…...

stm32G473的flash模式是单bank还是双bank?

今天突然有人stm32G473的flash模式是单bank还是双bank&#xff1f;由于时间太久&#xff0c;我真忘记了。搜搜发现&#xff0c;还真有人和我一样。见下面的链接&#xff1a;https://shequ.stmicroelectronics.cn/forum.php?modviewthread&tid644563 根据STM32G4系列参考手…...

PL0语法,分析器实现!

简介 PL/0 是一种简单的编程语言,通常用于教学编译原理。它的语法结构清晰,功能包括常量定义、变量声明、过程(子程序)定义以及基本的控制结构(如条件语句和循环语句)。 PL/0 语法规范 PL/0 是一种教学用的小型编程语言,由 Niklaus Wirth 设计,用于展示编译原理的核…...

C++八股 —— 单例模式

文章目录 1. 基本概念2. 设计要点3. 实现方式4. 详解懒汉模式 1. 基本概念 线程安全&#xff08;Thread Safety&#xff09; 线程安全是指在多线程环境下&#xff0c;某个函数、类或代码片段能够被多个线程同时调用时&#xff0c;仍能保证数据的一致性和逻辑的正确性&#xf…...

Kafka入门-生产者

生产者 生产者发送流程&#xff1a; 延迟时间为0ms时&#xff0c;也就意味着每当有数据就会直接发送 异步发送API 异步发送和同步发送的不同在于&#xff1a;异步发送不需要等待结果&#xff0c;同步发送必须等待结果才能进行下一步发送。 普通异步发送 首先导入所需的k…...

Selenium常用函数介绍

目录 一&#xff0c;元素定位 1.1 cssSeector 1.2 xpath 二&#xff0c;操作测试对象 三&#xff0c;窗口 3.1 案例 3.2 窗口切换 3.3 窗口大小 3.4 屏幕截图 3.5 关闭窗口 四&#xff0c;弹窗 五&#xff0c;等待 六&#xff0c;导航 七&#xff0c;文件上传 …...

从 GreenPlum 到镜舟数据库:杭银消费金融湖仓一体转型实践

作者&#xff1a;吴岐诗&#xff0c;杭银消费金融大数据应用开发工程师 本文整理自杭银消费金融大数据应用开发工程师在StarRocks Summit Asia 2024的分享 引言&#xff1a;融合数据湖与数仓的创新之路 在数字金融时代&#xff0c;数据已成为金融机构的核心竞争力。杭银消费金…...

提升移动端网页调试效率:WebDebugX 与常见工具组合实践

在日常移动端开发中&#xff0c;网页调试始终是一个高频但又极具挑战的环节。尤其在面对 iOS 与 Android 的混合技术栈、各种设备差异化行为时&#xff0c;开发者迫切需要一套高效、可靠且跨平台的调试方案。过去&#xff0c;我们或多或少使用过 Chrome DevTools、Remote Debug…...

MyBatis中关于缓存的理解

MyBatis缓存 MyBatis系统当中默认定义两级缓存&#xff1a;一级缓存、二级缓存 默认情况下&#xff0c;只有一级缓存开启&#xff08;sqlSession级别的缓存&#xff09;二级缓存需要手动开启配置&#xff0c;需要局域namespace级别的缓存 一级缓存&#xff08;本地缓存&#…...

Leetcode33( 搜索旋转排序数组)

题目表述 整数数组 nums 按升序排列&#xff0c;数组中的值 互不相同 。 在传递给函数之前&#xff0c;nums 在预先未知的某个下标 k&#xff08;0 < k < nums.length&#xff09;上进行了 旋转&#xff0c;使数组变为 [nums[k], nums[k1], …, nums[n-1], nums[0], nu…...