随笔小记：SpringBoot 3 集成 SpringDoc OpenAPI

本篇主要是介绍针对一个新起的 SpringBoot 3.x 项目，如何快速集成 SpringDoc OpenAPI 来实现 API 管理。

springdoc-openapi 与 Spring Boot 的版本兼容性

在开始接入之前，一定要先关注这个版本兼容性匹配，根据你当前项目所使用的 springboot 版本来选择 springdoc openapi 的版本。springdoc-openapi 2.x 与 spring-boot 3 兼容，具体版本对应表如下：

Spring Boot Versions	Springdoc OpenAPI Versions
3.4.x	2.7.x - 2.8.x
3.3.x	2.6.x
3.2.x	2.3.x - 2.5.x
3.1.x	2.2.x
3.0.x	2.0.x - 2.1.x
2.7.x, 1.5.x	1.6.0+
2.6.x, 1.5.x	1.6.0+
2.5.x, 1.5.x	1.5.9+
2.4.x, 1.5.x	1.5.0+
2.3.x, 1.5.x	1.4.0+
2.2.x, 1.5.x	1.2.1+
2.0.x, 1.5.x	1.0.0+

如果你集成过程中可能会出现类似以下的报错信息，则原因就是版本不匹配导致

bash

代码解读

复制代码

Caused by: java.lang.NoClassDefFoundError: org/springframework/web/servlet/resource/LiteWebJarsResourceResolver at java.base/java.lang.ClassLoader.defineClass1(Native Method) at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1027) at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150) at java.base/jdk.internal.loader.BuiltinClassLoader.defineClass(BuiltinClassLoader.java:862) at java.base/jdk.internal.loader.BuiltinClassLoader.findClassOnClassPathOrNull(BuiltinClassLoader.java:760) at java.base/jdk.internal.loader.BuiltinClassLoader.loadClassOrNull(BuiltinClassLoader.java:681) at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:639) at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188) at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526) at java.base/java.lang.Class.getDeclaredMethods0(Native Method) at java.base/java.lang.Class.privateGetDeclaredMethods(Class.java:3578) at java.base/java.lang.Class.getDeclaredMethods(Class.java:2676) at org.springframework.util.ReflectionUtils.getDeclaredMethods(ReflectionUtils.java:465) ... 56 more Caused by: java.lang.ClassNotFoundException: org.springframework.web.servlet.resource.LiteWebJarsResourceResolver at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641) at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188) at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526) ... 69 more

快速开始

要在 Spring Boot 与 Swagger UI 之间进行集成，只需将该库添加到项目依赖中（无需额外配置）。

xml

代码解读

复制代码

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

如果不需要 Swagger UI 界面，则可以只引入

xml

代码解读

复制代码

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

Springdoc-openapi 模块的层级关系大致如下，通过这张图可以比较清晰的了解到 Springdoc-openapi 的结构。

实际上，在引入依赖之后，其他什么操作都不用，直接启动项目即可。然后通过下面两个链接来分别获取 Swagger UI 和 api-docs

bash

代码解读

复制代码

# 展示 Swagger UI http://localhost:8080/swagger-ui/index.html # 获取 api docs http://localhost:8080/v3/api-docs

这两个地址都是 springdoc openapi 默认的，如图你想自定义路径，可以通过下面两个配置修改：

bash

代码解读

复制代码

# swagger-ui 自定义 path springdoc.swagger-ui.path=/swagger-ui.html # /api-docs endpoint 自定义 path springdoc.api-docs.path=/api-docs

对 Actuator 的支持

Springdoc-openapi 实现了对 springboot Actuator 的支持。首先你需要在项目中引入 actuator 的依赖

xml

代码解读

复制代码

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>

然后需要在配置文件中将 actuator 的展示配置开启

properties

代码解读

复制代码

springdoc.show-actuator=true # 使用单独的 management port springdoc.use-management-port=true management.server.port=9090 # 将 openapi 和 swagger-ui 暴露出来 management.endpoints.web.exposure.include=openapi, swagger-ui

这里需要注意下，如果你配置了 springdoc.use-management-port=true ，但是没有配置 management.server.port，则启动时会报如下的错误：

vbnet

代码解读

复制代码

Description: Parameter 3 of method indexPageTransformer in org.springdoc.webmvc.ui.SwaggerConfig required a bean of type 'org.springdoc.webmvc.ui.SwaggerWelcomeCommon' that could not be found. Action: Consider defining a bean of type 'org.springdoc.webmvc.ui.SwaggerWelcomeCommon' in your configuration.

配置完成后，可以通过下面两个路径访问

bash

代码解读

复制代码

# 实际出现 404 http://localhost:9090/actuator/openapi # 正常 http://localhost:9090/actuator/swagger-ui

所以结论就是，还是别集成 Actuator 了。

总结

本篇完整的介绍了 SpringBoot 3 集成 SpringDoc OpenAPI 的过程，从版本兼容性、可能出现的报错信息以及是否需要集成 Actuator 等方面出来了具体的集成方式和建议；希望对你有所帮助。