随笔小记：SpringBoot 3 集成 SpringDoc OpenAPI

一个面向 Java 开发者的 Sring-Ai 示例工程项目，该项目是一个 Spring AI 快速入门的样例工程项目，旨在通过一些小的案例展示 Spring AI 框架的核心功能和使用方法。项目采用模块化设计，每个模块都专注于特定的功能领域，便于学习和扩展。欢迎感兴趣的小伙伴们关注和 Star。

项目地址：github.com/java-ai-tec...

本篇主要是介绍针对一个新起的 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 等方面出来了具体的集成方式和建议；希望对你有所帮助。