Apache ShenYu项目Spring Boot 3.x升级中的Swagger兼容性问题解析

背景介绍

Apache ShenYu作为一款高性能的微服务API网关，在其示例项目中提供了基于Swagger的API文档支持。然而，随着Spring Boot升级到3.x版本，原有的Springfox Swagger2实现出现了严重的兼容性问题，导致示例项目无法正常启动。本文将深入分析这一问题，并探讨解决方案。

问题现象分析

当开发者尝试在Spring Boot 3.3.1环境下运行shenyu-examples-http-swagger2模块时，会遇到应用启动失败的情况。从错误日志中可以观察到几个关键点：

1. 核心错误信息：'void org.springframework.util.Assert.notNull(java.lang.Object)'方法不存在
2. 依赖冲突：Springfox的spring-plugin-core与Spring Boot 3.x的spring-core存在版本不兼容
3. 调用链：从ApiDocumentationScanner到documentationPluginsManager的整个初始化过程失败

技术根源探究

Springfox与Spring Boot 3.x的兼容性问题

Springfox Swagger2（2.9.2版本）是基于较旧版本的Spring框架开发的，其核心依赖spring-plugin-core1.2.0.RELEASE版本中使用的Assert.notNull()方法签名在Spring 6.x中已经发生了变化。Spring Boot 3.x默认使用Spring 6.x框架，这导致了方法调用失败。

方法签名变更细节

在Spring 5.x及以下版本中，Assert.notNull()方法的签名是：

public static void notNull(Object object)

而在Spring 6.x中，该方法被重载为：

public static void notNull(Object object, String message)

这种变化使得Springfox在Spring Boot 3.x环境下无法找到兼容的方法实现。

解决方案

方案一：降级Spring Boot版本

最直接的解决方案是将Spring Boot降级到2.x版本，但这意味着无法使用Spring Boot 3.x的新特性，不是长远之计。

方案二：迁移到Springdoc OpenAPI

更合理的方案是将项目从Springfox迁移到Springdoc OpenAPI，这是目前官方推荐的Swagger集成方案，完全支持Spring Boot 3.x。

迁移步骤

1. 移除Springfox依赖： 删除pom.xml中所有springfox相关的依赖项

2. 添加Springdoc依赖：

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

3. 配置类调整： 将原有的SwaggerConfiguration替换为OpenAPI配置：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI shenYuOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("ShenYu API")
                .description("ShenYu HTTP API Documentation")
                .version("v1.0.0")
                .license(new License().name("Apache 2.0")));
    }
}

4. 注解替换： 将原有的@Api、@ApiOperation等注解替换为@Tag、@Operation等OpenAPI注解

迁移后的优势

1. 更好的兼容性：Springdoc专为Spring Boot 3.x设计，不存在兼容性问题
2. 支持OpenAPI 3.0：提供更现代的API文档标准
3. 更简洁的配置：减少了大量样板代码
4. 更好的性能：Springdoc的实现更加轻量高效

实施建议

对于Apache ShenYu项目，建议：

1. 在master分支中尽快完成Swagger实现的迁移
2. 更新相关文档，说明Spring Boot 3.x下的API文档配置方式
3. 考虑提供同时支持Spring Boot 2.x和3.x的配置示例
4. 在示例项目中添加关于API文档的测试用例

总结

Spring Boot 3.x的升级带来了许多新特性，但也需要项目依赖的相应更新。对于Apache ShenYu这样的网关项目来说，保持与最新Spring Boot版本的兼容性至关重要。从Springfox迁移到Springdoc不仅解决了当前的兼容性问题，还为项目带来了更现代的API文档支持，是值得推荐的解决方案。开发者在进行类似升级时，应当充分评估依赖兼容性，并制定合理的迁移计划。