SpringBoot 3.x集成Swagger UI 404问题解决方案

1. 问题现象与背景分析

最近在升级SpringBoot到3.x版本时，发现一个奇怪的现象：项目中的Swagger文档接口/v3/api-docs能够正常返回JSON数据，但访问/swagger-ui.html页面却始终报404错误。这个问题困扰了我整整两天，经过反复排查和测试，终于找到了根本原因和解决方案。

SpringBoot 3.x版本对Swagger的支持发生了重大变化。原先广泛使用的springfox-swagger已经不再维护，官方推荐迁移到springdoc-openapi。这个迁移过程看似简单，实则暗藏玄机。很多开发者（包括我）在升级时都会遇到HTML页面无法访问的问题，而JSON接口却能正常工作。

2. 环境配置检查

2.1 依赖配置验证

首先检查pom.xml中的依赖配置是否正确。SpringBoot 3.x需要以下最小依赖配置：

xml复制<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

常见错误是只引入了核心依赖而缺少UI依赖：

xml复制<!-- 错误的配置示例 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.1.0</version>
</dependency>

2.2 配置文件检查

application.properties或application.yml中需要确保以下配置：

properties复制# 启用Swagger UI
springdoc.swagger-ui.enabled=true
# 设置自定义路径（可选）
springdoc.swagger-ui.path=/swagger-ui.html

注意：SpringBoot 3.x默认情况下不会自动配置静态资源映射，这是导致404问题的关键原因之一。

3. 根本原因分析

3.1 资源映射机制变化

SpringBoot 3.x对静态资源处理机制做了重大调整。在2.x版本中，Swagger UI的静态资源会自动映射到classpath:/META-INF/resources/webjars/目录下。但在3.x版本中，这个自动映射机制发生了变化，需要显式配置。

3.2 路径匹配策略变更

SpringBoot 3.x默认使用PathPatternParser而不是AntPathMatcher进行路径匹配。这导致一些传统的URL匹配模式可能失效，特别是对于静态资源的处理。

3.3 版本兼容性问题

springdoc-openapi的不同版本对SpringBoot 3.x的支持程度不同。使用过旧或过新的版本都可能导致UI无法正常访问。

4. 完整解决方案

4.1 方案一：添加资源处理器

在配置类中添加以下代码：

java复制@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
                .resourceChain(false);
    }
}

4.2 方案二：更新访问路径

由于路径策略变更，建议使用新的默认访问路径：

code复制http://localhost:8080/swagger-ui/index.html

替代旧的：

code复制http://localhost:8080/swagger-ui.html

4.3 方案三：完整配置示例

完整的配置类应该包含以下内容：

java复制@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("API文档")
                        .version("1.0")
                        .description("项目API文档"));
    }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
                .resourceChain(false);
        
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
    }
}

5. 常见问题排查

5.1 问题一：仍然返回404

检查步骤：

1. 确认依赖树中没有springfox残留
2. 检查是否有自定义的WebSecurityConfig拦截了请求
3. 查看控制台是否有资源加载错误

解决方案：

java复制@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .anyRequest().authenticated());
        return http.build();
    }
}

5.2 问题二：页面加载但样式丢失

这通常是由于静态资源路径配置不正确导致的。解决方案：

1. 检查浏览器控制台报错
2. 确保资源处理器配置了正确的路径
3. 尝试清除浏览器缓存

5.3 问题三：接口文档不完整

如果发现/v3/api-docs返回的数据不完整：

1. 检查Controller是否使用了正确的注解
2. 确认方法返回值类型是否被正确识别
3. 尝试添加@Operation等注解明确文档信息

java复制@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {
    
    @GetMapping("/users")
    @Operation(summary = "获取用户列表")
    public List<User> getUsers() {
        // 实现代码
    }
}

6. 高级配置技巧

6.1 自定义UI配置

可以在application.properties中添加各种UI自定义配置：

properties复制# 修改主题
springdoc.swagger-ui.theme=flattop
# 禁用验证
springdoc.swagger-ui.validatorUrl=
# 默认展开深度
springdoc.swagger-ui.docExpansion=none

6.2 分组API文档

对于大型项目，可以考虑分组展示API：

java复制@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public-apis")
            .pathsToMatch("/public/**")
            .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin-apis")
            .pathsToMatch("/admin/**")
            .build();
}

6.3 安全集成

如果项目使用了Spring Security，需要确保正确配置：

java复制@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
                .anyRequest().authenticated())
            .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
        return http.build();
    }
}

7. 性能优化建议

7.1 生产环境配置

在生产环境中，建议禁用Swagger UI：

properties复制springdoc.swagger-ui.enabled=false
springdoc.api-docs.enabled=false

可以通过Profile来控制：

java复制@Profile("!prod")
@Configuration
public class OpenApiConfig {
    // 配置内容
}

7.2 缓存配置

对于频繁访问的文档，可以添加缓存控制：

java复制@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/")
                .setCacheControl(CacheControl.maxAge(1, TimeUnit.HOURS));
    }
}

7.3 文档导出

可以定期将API文档导出为JSON文件备份：

bash复制curl http://localhost:8080/v3/api-docs > api-docs.json

或者使用Maven插件在构建时自动导出：

xml复制<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>exec</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <executable>curl</executable>
        <arguments>
            <argument>http://localhost:${server.port}/v3/api-docs</argument>
            <argument>-o</argument>
            <argument>${project.build.directory}/api-docs.json</argument>
        </arguments>
    </configuration>
</plugin>

8. 版本兼容性矩阵

不同SpringBoot版本对应的springdoc版本选择：

重要提示：不要盲目使用最新版本，应该根据SpringBoot版本选择对应的springdoc版本。

9. 替代方案比较

如果仍然遇到问题，可以考虑以下替代方案：

1. SpringDoc OpenAPI Starter WebFlux UI
   适用于WebFlux项目

   xml复制<dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
       <version>2.1.0</version>
   </dependency>
   

2. 手动集成Swagger UI
   完全手动控制UI资源

   java复制@Override
   public void addResourceHandlers(ResourceHandlerRegistry registry) {
       registry.addResourceHandler("/custom-swagger/**")
           .addResourceLocations("classpath:/META-INF/resources/")
           .resourceChain(false)
           .addResolver(new PathResourceResolver() {
               @Override
               protected Resource getResource(String resourcePath, Resource location) throws IOException {
                   Resource requestedResource = location.createRelative(resourcePath);
                   return requestedResource.exists() && requestedResource.isReadable() ? requestedResource
                           : new ClassPathResource("/META-INF/resources/index.html");
               }
           });
   }
   

3. 使用Redoc替代Swagger UI

   xml复制<dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
       <version>2.1.0</version>
   </dependency>
   

   然后单独集成Redoc

10. 最佳实践总结

经过多次项目实践，我总结了以下最佳实践：

1. 始终使用SpringBoot版本对应的springdoc版本
2. 显式配置资源处理器，不要依赖自动配置
3. 生产环境一定要禁用Swagger UI
4. 使用分组功能组织大型项目的API文档
5. 为重要接口添加详细的@Operation描述
6. 定期导出API文档作为项目文档的一部分
7. 考虑使用自定义主题提升使用体验
8. 集成到CI/CD流程中自动验证API文档变更

最后分享一个实用技巧：可以在开发环境配置springdoc.show-actuator=true来包含Actuator端点的文档，这对于监控系统集成非常有用。