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

通过Wrangler CLI在worker中创建数据库和表

官方使用文档&#xff1a;Getting started Cloudflare D1 docs 创建数据库 在命令行中执行完成之后&#xff0c;会在本地和远程创建数据库&#xff1a; npx wranglerlatest d1 create prod-d1-tutorial 在cf中就可以看到数据库&#xff1a; 现在&#xff0c;您的Cloudfla…...

Qt Widget类解析与代码注释

#include "widget.h" #include "ui_widget.h"Widget::Widget(QWidget *parent): QWidget(parent), ui(new Ui::Widget) {ui->setupUi(this); }Widget::~Widget() {delete ui; }//解释这串代码&#xff0c;写上注释 当然可以&#xff01;这段代码是 Qt …...

Opencv中的addweighted函数

一.addweighted函数作用 addweighted&#xff08;&#xff09;是OpenCV库中用于图像处理的函数&#xff0c;主要功能是将两个输入图像&#xff08;尺寸和类型相同&#xff09;按照指定的权重进行加权叠加&#xff08;图像融合&#xff09;&#xff0c;并添加一个标量值&#x…...

在四层代理中还原真实客户端ngx_stream_realip_module

一、模块原理与价值 PROXY Protocol 回溯 第三方负载均衡&#xff08;如 HAProxy、AWS NLB、阿里 SLB&#xff09;发起上游连接时&#xff0c;将真实客户端 IP/Port 写入 PROXY Protocol v1/v2 头。Stream 层接收到头部后&#xff0c;ngx_stream_realip_module 从中提取原始信息…...

【决胜公务员考试】求职OMG——见面课测验1

2025最新版&#xff01;&#xff01;&#xff01;6.8截至答题&#xff0c;大家注意呀&#xff01; 博主码字不易点个关注吧,祝期末顺利~~ 1.单选题(2分) 下列说法错误的是:&#xff08; B &#xff09; A.选调生属于公务员系统 B.公务员属于事业编 C.选调生有基层锻炼的要求 D…...

SpringCloudGateway 自定义局部过滤器

场景&#xff1a; 将所有请求转化为同一路径请求&#xff08;方便穿网配置&#xff09;在请求头内标识原来路径&#xff0c;然后在将请求分发给不同服务 AllToOneGatewayFilterFactory import lombok.Getter; import lombok.Setter; import lombok.extern.slf4j.Slf4j; impor…...

爬虫基础学习day2

# 爬虫设计领域 工商&#xff1a;企查查、天眼查短视频&#xff1a;抖音、快手、西瓜 ---> 飞瓜电商&#xff1a;京东、淘宝、聚美优品、亚马逊 ---> 分析店铺经营决策标题、排名航空&#xff1a;抓取所有航空公司价格 ---> 去哪儿自媒体&#xff1a;采集自媒体数据进…...

css3笔记 (1) 自用

outline: none 用于移除元素获得焦点时默认的轮廓线 broder:0 用于移除边框 font-size&#xff1a;0 用于设置字体不显示 list-style: none 消除<li> 标签默认样式 margin: xx auto 版心居中 width:100% 通栏 vertical-align 作用于行内元素 / 表格单元格&#xff…...

OpenLayers 分屏对比(地图联动)

注&#xff1a;当前使用的是 ol 5.3.0 版本&#xff0c;天地图使用的key请到天地图官网申请&#xff0c;并替换为自己的key 地图分屏对比在WebGIS开发中是很常见的功能&#xff0c;和卷帘图层不一样的是&#xff0c;分屏对比是在各个地图中添加相同或者不同的图层进行对比查看。…...

mac 安装homebrew (nvm 及git)

mac 安装nvm 及git 万恶之源 mac 安装这些东西离不开Xcode。及homebrew 一、先说安装git步骤 通用&#xff1a; 方法一&#xff1a;使用 Homebrew 安装 Git&#xff08;推荐&#xff09; 步骤如下&#xff1a;打开终端&#xff08;Terminal.app&#xff09; 1.安装 Homebrew…...