当前位置: 首页 > 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;数据库未…...

观成科技:隐蔽隧道工具Ligolo-ng加密流量分析

1.工具介绍 Ligolo-ng是一款由go编写的高效隧道工具&#xff0c;该工具基于TUN接口实现其功能&#xff0c;利用反向TCP/TLS连接建立一条隐蔽的通信信道&#xff0c;支持使用Let’s Encrypt自动生成证书。Ligolo-ng的通信隐蔽性体现在其支持多种连接方式&#xff0c;适应复杂网…...

iOS 26 携众系统重磅更新,但“苹果智能”仍与国行无缘

美国西海岸的夏天&#xff0c;再次被苹果点燃。一年一度的全球开发者大会 WWDC25 如期而至&#xff0c;这不仅是开发者的盛宴&#xff0c;更是全球数亿苹果用户翘首以盼的科技春晚。今年&#xff0c;苹果依旧为我们带来了全家桶式的系统更新&#xff0c;包括 iOS 26、iPadOS 26…...

css实现圆环展示百分比,根据值动态展示所占比例

代码如下 <view class""><view class"circle-chart"><view v-if"!!num" class"pie-item" :style"{background: conic-gradient(var(--one-color) 0%,#E9E6F1 ${num}%),}"></view><view v-else …...

《Qt C++ 与 OpenCV:解锁视频播放程序设计的奥秘》

引言:探索视频播放程序设计之旅 在当今数字化时代,多媒体应用已渗透到我们生活的方方面面,从日常的视频娱乐到专业的视频监控、视频会议系统,视频播放程序作为多媒体应用的核心组成部分,扮演着至关重要的角色。无论是在个人电脑、移动设备还是智能电视等平台上,用户都期望…...

P3 QT项目----记事本(3.8)

3.8 记事本项目总结 项目源码 1.main.cpp #include "widget.h" #include <QApplication> int main(int argc, char *argv[]) {QApplication a(argc, argv);Widget w;w.show();return a.exec(); } 2.widget.cpp #include "widget.h" #include &q…...

Linux-07 ubuntu 的 chrome 启动不了

文章目录 问题原因解决步骤一、卸载旧版chrome二、重新安装chorme三、启动不了&#xff0c;报错如下四、启动不了&#xff0c;解决如下 总结 问题原因 在应用中可以看到chrome&#xff0c;但是打不开(说明&#xff1a;原来的ubuntu系统出问题了&#xff0c;这个是备用的硬盘&a…...

NLP学习路线图(二十三):长短期记忆网络(LSTM)

在自然语言处理(NLP)领域,我们时刻面临着处理序列数据的核心挑战。无论是理解句子的结构、分析文本的情感,还是实现语言的翻译,都需要模型能够捕捉词语之间依时序产生的复杂依赖关系。传统的神经网络结构在处理这种序列依赖时显得力不从心,而循环神经网络(RNN) 曾被视为…...

优选算法第十二讲:队列 + 宽搜 优先级队列

优选算法第十二讲&#xff1a;队列 宽搜 && 优先级队列 1.N叉树的层序遍历2.二叉树的锯齿型层序遍历3.二叉树最大宽度4.在每个树行中找最大值5.优先级队列 -- 最后一块石头的重量6.数据流中的第K大元素7.前K个高频单词8.数据流的中位数 1.N叉树的层序遍历 2.二叉树的锯…...

springboot整合VUE之在线教育管理系统简介

可以学习到的技能 学会常用技术栈的使用 独立开发项目 学会前端的开发流程 学会后端的开发流程 学会数据库的设计 学会前后端接口调用方式 学会多模块之间的关联 学会数据的处理 适用人群 在校学生&#xff0c;小白用户&#xff0c;想学习知识的 有点基础&#xff0c;想要通过项…...

Docker拉取MySQL后数据库连接失败的解决方案

在使用Docker部署MySQL时&#xff0c;拉取并启动容器后&#xff0c;有时可能会遇到数据库连接失败的问题。这种问题可能由多种原因导致&#xff0c;包括配置错误、网络设置问题、权限问题等。本文将分析可能的原因&#xff0c;并提供解决方案。 一、确认MySQL容器的运行状态 …...