Spring Boot 3集成Swagger常见问题与解决方案

1. 问题背景与现象描述

最近在将老项目迁移到Spring Boot 3时，遇到了Swagger集成的一系列问题。最典型的表现是访问/doc.html时出现404错误，以及配置了安全拦截器后出现的401 Unauthorized问题。这些问题在Spring Boot 2.x时代很少遇到，但在新版本中却成了"标配"。

实际开发中，我遇到了以下具体现象：

• 访问http://localhost:8080/doc.html返回404 Not Found
• 配置了Spring Security后，访问Swagger UI时持续弹出401 Unauthorized
• 控制台没有任何错误日志，但页面就是无法正常显示
• 偶尔能看到Swagger资源加载成功，但API文档部分显示"No API definition provided"

2. Spring Boot 3与Swagger的兼容性问题

2.1 版本变迁带来的破坏性变更

Spring Boot 3最大的变化是从Jakarta EE 9开始全面采用jakarta包名替代javax。这个改动影响了许多依赖库的兼容性，包括Swagger相关组件。

传统Spring Boot 2.x项目中常用的springfox-swagger2和springfox-swagger-ui在Spring Boot 3中完全无法工作，原因在于：

1. springfox长期未更新，最新版本停留在2020年
2. springfox内部依赖的spring-plugin-core等组件与Spring Boot 3不兼容
3. 核心注解如@Api等仍使用javax包路径

2.2 官方推荐的替代方案

Spring官方团队推荐使用springdoc-openapi作为Swagger在Spring Boot 3时代的替代方案。其优势在于：

• 原生支持Jakarta EE 9+
• 自动适配Spring MVC和WebFlux
• 提供OpenAPI 3.0规范支持
• 活跃的社区维护

核心依赖变更对比：

3. 解决doc.html 404问题全流程

3.1 正确依赖配置

首先需要在pom.xml中移除所有springfox相关依赖，添加正确的springdoc依赖：

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

常见错误配置：

1. 同时存在springfox和springdoc依赖导致冲突
2. 使用了错误的artifactId（如webflux-ui用于MVC项目）
3. 版本号过低缺少必要功能

3.2 访问路径的变化

springdoc的默认访问路径与springfox不同：

注意：/doc.html是springdoc提供的备用UI界面，其实现原理是通过转发到/swagger-ui.html。如果直接访问/doc.html报404，但/swagger-ui.html能正常访问，属于预期行为。

3.3 自定义路径配置

如需修改默认路径，可在application.yml中配置：

yaml复制springdoc:
  swagger-ui:
    path: /custom-docs.html
  api-docs:
    path: /custom-api-docs

配置后需要特别注意：

1. 路径必须以/开头
2. 避免使用常见路径如/api等可能与其他接口冲突
3. 修改后所有相关路径都需要同步更新

4. 解决401 Unauthorized拦截问题

4.1 Spring Security的默认拦截

Spring Security 6.x默认会拦截所有请求，包括静态资源。这会导致以下问题：

1. 访问Swagger UI时弹出认证对话框
2. 加载API文档时返回401
3. 静态资源如CSS/JS无法加载

4.2 精确配置放行规则

推荐的安全配置方案：

java复制@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private static final String[] SWAGGER_WHITELIST = {
        "/swagger-ui.html",
        "/swagger-ui/**",
        "/v3/api-docs/**",
        "/doc.html",
        "/webjars/**"
    };

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(SWAGGER_WHITELIST).permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(withDefaults());
        return http.build();
    }
}

关键点说明：

1. 必须放行swagger-ui/**路径以加载静态资源
2. /v3/api-docs/**是API文档的JSON数据源
3. /webjars/**包含Swagger UI所需的前端库

4.3 常见配置误区

实践中遇到的典型错误配置：

1. 只放行HTML页面不放行静态资源：

java复制.requestMatchers("/swagger-ui.html").permitAll()

结果：页面能打开但样式丢失，控制台报JS/CSS 401错误

2. 路径模式不匹配：

java复制.requestMatchers("/swagger-ui/*").permitAll()

问题：*不匹配多级路径，导致/swagger-ui/index.html仍被拦截

3. 忽略webjars路径：

java复制.requestMatchers("/swagger-ui/**").permitAll()

缺陷：缺少/webjars/**会导致部分前端库加载失败

5. 高级配置与优化技巧

5.1 分组API文档

大型项目中可能需要按模块分组展示API：

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

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

访问方式：

• /v3/api-docs/user-service
• /v3/api-docs/admin-service
• UI界面右上角可选择不同分组

5.2 自定义文档信息

通过配置OpenAPI Bean增强文档信息：

java复制@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("API文档")
                    .version("1.0")
                    .contact(new Contact().name("技术支持"))
                    .license(new License().name("Apache 2.0")))
            .externalDocs(new ExternalDocumentation()
                    .description("项目Wiki")
                    .url("https://wiki.example.com"));
}

5.3 生产环境安全建议

1. 通过Profile控制Swagger的启用：

yaml复制spring:
  profiles:
    active: dev

---
spring:
  config:
    activate:
      on-profile: prod
springdoc:
  swagger-ui:
    enabled: false

2. 添加IP白名单限制：

java复制.requestMatchers(SWAGGER_WHITELIST).hasIpAddress("192.168.1.0/24")

3. 启用Basic认证：

java复制springdoc:
  swagger-ui:
    enabled: true
    config-url: /v3/api-docs/swagger-config
    operations-sorter: alpha
    tags-sorter: alpha
    doc-expansion: none
  api-docs:
    enabled: true
  basic:
    enabled: true
    username: admin
    password: secret

6. 疑难问题排查指南

6.1 404问题排查流程

1. 确认依赖是否正确：

bash复制mvn dependency:tree | grep springdoc

2. 检查自动配置是否生效：

java复制@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
        System.out.println("Swagger UI: http://localhost:8080/swagger-ui.html");
    }
}

3. 查看内置端点信息：

bash复制curl http://localhost:8080/actuator/mappings | grep swagger

6.2 401问题排查步骤

1. 确认安全配置是否加载：

java复制@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    // 检查配置类是否被扫描到
}

2. 调试请求匹配过程：

java复制.securityMatcher("/swagger-ui/**").permitAll()

3. 查看过滤器链顺序：

java复制http.addFilterBefore(..., UsernamePasswordAuthenticationFilter.class);

6.3 常见错误解决方案

1. 问题：No API definition provided

• 检查Controller是否有@RestController注解
• 确认方法上有@RequestMapping或@GetMapping等注解
• 验证分组配置是否正确包含目标路径

2. 问题：Failed to load API definition

• 检查/v3/api-docs是否能正常返回JSON
• 确认没有Jackson序列化问题
• 验证响应头Content-Type是否为application/json

3. 问题：样式丢失或JS错误

• 检查浏览器控制台网络请求
• 确认所有静态资源路径已放行
• 清除浏览器缓存强制刷新

7. 最佳实践总结

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

1. 版本选择建议：

• Spring Boot 3.1.x + springdoc-openapi 2.x
• 避免使用snapshot版本
• 定期检查版本兼容性

2. 配置模板推荐：

yaml复制springdoc:
  show-actuator: true
  cache:
    disabled: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  model-and-view-allowed: true
  override-with-generic-response: false

3. 注解使用技巧：

• 用@Tag代替过时的@Api
• @Operation替代@ApiOperation
• @Parameter替代@ApiParam
• 使用@Hidden隐藏内部API

4. 性能优化方向：

• 生产环境禁用Swagger UI
• 使用@Profile限制开发环境加载
• 配置缓存策略减少文档生成开销

5. 扩展思路：

• 集成Knife4j增强UI体验
• 自动生成TypeScript客户端代码
• 结合GitLab Wiki实现文档同步