Spring Boot3+Java19 Maven项目集成Swagger-UI报错求助

1. 移除错误注解 #

Spring Boot 3.x 集成Swagger-UI用的是springdoc-openapi，不需要@EnableSwagger2——这个注解是旧版Springfox框架的，和springdoc完全不兼容，直接删掉代码里的这个注解。

2. 修复Repository方法的参数注解 #

控制台的NullPointerException核心原因是：Spring Data Repository的某个方法参数没有标注@Param注解，导致springdoc解析时无法获取注解实例而抛出空指针。

检查所有自定义的Repository接口，确保：

• 自定义@Query查询的方法，参数必须用@org.springframework.data.repository.query.Param绑定占位符
• 哪怕是派生查询方法，也建议加上@Param注解，避免反射解析参数名失败

示例：
错误写法：

@Query("SELECT u FROM User u WHERE u.username = :username")
User findByUsername(String username);

正确写法：

@Query("SELECT u FROM User u WHERE u.username = :username")
User findByUsername(@Param("username") String username);

3. 配置Maven编译参数（Java 19必填） #

Java 19默认编译时不会保留方法参数名，导致反射无法获取参数名，即使没写@Param也会触发解析错误。在pom.xml的build/plugins中添加编译插件配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version>
    <configuration>
        <source>19</source>
        <target>19</target>
        <!-- 保留参数名，支持反射获取 -->
        <parameters>true</parameters>
    </configuration>
</plugin>

4. 确认springdoc依赖版本 #

确保springdoc-openapi-starter-webmvc-ui的版本适配Spring Boot 3.0.3，推荐使用2.0.x稳定版，pom.xml依赖配置：

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

5. 排除冲突依赖 #

如果项目中之前引入过Springfox（swagger2/swagger-ui）相关依赖，需要全部移除，避免和springdoc产生依赖冲突。

完成以上步骤后，重新打包启动项目，访问http://localhost:8080/swagger-ui/index.html即可正常使用Swagger-UI。

内容的提问来源于stack exchange，提问作者Krzysztof Chwedziak