springboot3.x集成SpringDoc Swagger3

2024-03-07 12:12

本文主要是介绍springboot3.x集成SpringDoc Swagger3,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

近期将springboox2.x升级到了3.x,索性将swagger2也同步升级到swagger3,具体过程如下。

一、添加maven依赖

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version>
</dependency>

二、编写SpringDoc配置类

/*** spring doc配置*/
@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI restfulOpenAPI() {return new OpenAPI().info(new Info().title("springboot3.x demo").description("Spring Boot3 Restful API").version("V1.0.0").license(new License().name("访问SpringDoc官方网站").url("http://springdoc.org"))).externalDocs(new ExternalDocumentation().description("欢迎访问LDY的技术博客").url("https://blog.csdn.net/ldy1016"));}}

启动项目,在浏览器输入{ip}:{端口}/swagger-ui/index.html,查看效果,如127.0.0.1:8080/swagger-ui/index.html

三、添加swagger3注解

首先来看一下swagger2和swagger3中注解的对应关系,方便使用swagger2的同学升级到swagger3

swagger2swagger3说明
@Api@Tag用在请求的类上,表示对类的说明
@ApiIgnore@Hidden隐藏显示
@ApiImplicitParam@Parameter用在请求方法上,指定具体某一个请求参数的详细信息
@ApiImplicitParams@Parameters用在请求方法上,表示一组参数的说明
@ApiModel@Schema用于请求或者响应类上,说明请求或者响应数据
@ApiModelProperty@Schema用在属性上,描述响应类的属性用,swagger2中的hidden = true属性相当于swagger3中 的accessMode = READ_ONLY属性
@ApiOperation@Operation用在请求的方法上,说明方法的用途、作用对应注解中swagger2中的value和notes属性对应swagger3中的summary和description属性
@ApiParam@Parameter描述参数信息

 参考示例:

@Tag 描述整个类

@Tag(name = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {}

@Operation 用在请求的方法上,说明方法的用途、作用

    @Operation(summary = "查询用户列表接口",description = "部门用户信息")@GetMapping("/list")public List<UserVO> list(@RequestBody UserQueryParam param) {//TODO 查询用户信息并返回return null;}

@Schema 用于请求或者响应类上,说明请求或者响应数据,用在属性上,描述响应类的属性用

@Data
@Schema(title = "用户信息查询参数")
public class UserQueryParam implements Serializable {private static final long serialVersionUID = 4159622041608936674L;@Schema(title = "部门")private String department;@Schema(title = "姓名")private String name;@Schema(title = "性别",allowableValues = "0,1",example = "0")private Integer sex;}

打开swagger页面查看效果

四、自定义过滤器,防止swagger文档未授权访问

swagger3未授权访问的路径主要包括/v3/api-docs/swagger-ui/index.html

本人提供的解决方案就是通过过滤器的方式对请求进行验证,请求的时候需要在链接后面加上我们自定义的token参数,通过验证token判断是否是合法的访问,注意,添加过滤器后需要在启动类上加上@ServletComponentScan注解才能生效,具体实现如下:

import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.FilterConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;/*** 解决swagger-ui 未授权访问漏洞,需要在启动类加@ServletComponentScan注解* * @author ldy* @since V1.0.0*/
@Slf4j
@WebFilter(urlPatterns = {"/v3/api-docs","/swagger-ui/index.html"}, filterName = "springDocFilter")
public class SpringDocFilter implements Filter {/*** 访问swagger的token*/@Value("${swagger.token:123@abc}")private String swaggerToken;@Overridepublic void init(FilterConfig filterConfig) throws ServletException {Filter.super.init(filterConfig);}@Overridepublic void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain)throws IOException, ServletException {HttpServletRequest request = (HttpServletRequest) servletRequest;HttpServletResponse response = (HttpServletResponse) servletResponse;log.info("do springDocFilter,url:{}", request.getRequestURL());// 请求来源地址String referer = request.getHeader("referer");log.info("referer is {}", referer);/*** 1、请求来源地址为空,判断token是否匹配 2、请求来源地址不为空,判断来源地址是否包含正确的token*/if (StringUtils.isBlank(referer)) {// 获取tokenString token = request.getParameter("token");log.info("token is {}", token);// 来源地址为空,判断token是否匹配if (!StringUtils.equals(swaggerToken, token)) {log.error("禁止未授权访问,url:{}", request.getRequestURL());response.setStatus(403);servletResponse.setContentType("application/json");servletResponse.setCharacterEncoding("UTF-8");servletResponse.getWriter().write(JsonUtil.toJsonString(DJResult.error(-1, "禁止未授权访问", "")));return;}} else if (!referer.contains(swaggerToken)) {log.warn("禁止未授权访问,url:{}", request.getRequestURL());response.setStatus(403);servletResponse.setContentType("application/json");servletResponse.setCharacterEncoding("UTF-8");servletResponse.getWriter().write(JsonUtil.toJsonString(DJResult.error(-1, "禁止未授权访问", "")));return;}filterChain.doFilter(servletRequest, servletResponse);}@Overridepublic void destroy() {Filter.super.destroy();}
}

通过添加如上所示的过滤器后,我们就可以通过在路径后面加上token参数进行访问文档地址了,如:127.0.0.1:8080/swagger-ui/index.html?token=123@abc

没有加token参数或者token参数匹配不上的请求会直接返回“禁止未授权访问”。这里的token尽量设置复杂一点。

这篇关于springboot3.x集成SpringDoc Swagger3的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/783467

相关文章

SpringBoot集成LiteFlow实现轻量级工作流引擎的详细过程

《SpringBoot集成LiteFlow实现轻量级工作流引擎的详细过程》LiteFlow是一款专注于逻辑驱动流程编排的轻量级框架,它以组件化方式快速构建和执行业务流程,有效解耦复杂业务逻辑,下面给大... 目录一、基础概念1.1 组件(Component)1.2 规则(Rule)1.3 上下文(Conte

Springboot3+将ID转为JSON字符串的详细配置方案

《Springboot3+将ID转为JSON字符串的详细配置方案》:本文主要介绍纯后端实现Long/BigIntegerID转为JSON字符串的详细配置方案,s基于SpringBoot3+和Spr... 目录1. 添加依赖2. 全局 Jackson 配置3. 精准控制(可选)4. OpenAPI (Spri

SpringBoot3中使用虚拟线程的完整步骤

《SpringBoot3中使用虚拟线程的完整步骤》在SpringBoot3中使用Java21+的虚拟线程(VirtualThreads)可以显著提升I/O密集型应用的并发能力,这篇文章为大家介绍了详细... 目录1. 环境准备2. 配置虚拟线程方式一:全局启用虚拟线程(Tomcat/Jetty)方式二:异步

使用vscode搭建pywebview集成vue项目实践

《使用vscode搭建pywebview集成vue项目实践》:本文主要介绍使用vscode搭建pywebview集成vue项目实践,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地... 目录环境准备项目源码下载项目说明调试与生成可执行文件核心代码说明总结本节我们使用pythonpywebv

Maven项目中集成数据库文档生成工具的操作步骤

《Maven项目中集成数据库文档生成工具的操作步骤》在Maven项目中,可以通过集成数据库文档生成工具来自动生成数据库文档,本文为大家整理了使用screw-maven-plugin(推荐)的完... 目录1. 添加插件配置到 pom.XML2. 配置数据库信息3. 执行生成命令4. 高级配置选项5. 注意事

Java集成Onlyoffice的示例代码及场景分析

《Java集成Onlyoffice的示例代码及场景分析》:本文主要介绍Java集成Onlyoffice的示例代码及场景分析,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要... 需求场景:实现文档的在线编辑,团队协作总结:两个接口 + 前端页面 + 配置项接口1:一个接口,将o

Swagger2与Springdoc集成与使用详解

《Swagger2与Springdoc集成与使用详解》:本文主要介绍Swagger2与Springdoc集成与使用方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐... 目录1. 依赖配置2. 基础配置2.1 启用 Springdoc2.2 自定义 OpenAPI 信息3.

Spring Boot 集成 Solr 的详细示例

《SpringBoot集成Solr的详细示例》:本文主要介绍SpringBoot集成Solr的详细示例,本文通过实例代码给大家介绍的非常详细,感兴趣的朋友一起看看吧... 目录环境准备添加依赖配置 Solr 连接定义实体类编写 Repository 接口创建 Service 与 Controller示例运行

Spring Boot集成SLF4j从基础到高级实践(最新推荐)

《SpringBoot集成SLF4j从基础到高级实践(最新推荐)》SLF4j(SimpleLoggingFacadeforJava)是一个日志门面(Facade),不是具体的日志实现,这篇文章主要介... 目录一、日志框架概述与SLF4j简介1.1 为什么需要日志框架1.2 主流日志框架对比1.3 SLF4

Spring Boot集成Logback终极指南之从基础到高级配置实战指南

《SpringBoot集成Logback终极指南之从基础到高级配置实战指南》Logback是一个可靠、通用且快速的Java日志框架,作为Log4j的继承者,由Log4j创始人设计,:本文主要介绍... 目录一、Logback简介与Spring Boot集成基础1.1 Logback是什么?1.2 Sprin