随笔小记：SpringBoot 3 集成 SpringDoc OpenAPI

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

本篇主要是介绍针对一个新起的 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+

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

Caused by: java.lang.NoClassDefFoundError: org/springframework/web/servlet/resource/LiteWebJarsResourceResolverat 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.LiteWebJarsResourceResolverat 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 之间进行集成，只需将该库添加到项目依赖中（无需额外配置）。

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

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

<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

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

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

# 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 的依赖

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

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

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，则启动时会报如下的错误：

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.

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

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

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

总结

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