Spring Boot 3集成springdoc-openapi

关键原因：Spring Boot 3需要改用springdoc-openapi-starter-webmvc-ui依赖，v1.x版本不再兼容Jakarta EE规范

问题描述

在Spring Boot 3项目中添加springdoc-openapi-ui依赖后，访问/swagger-ui.html时出现404错误，配置如下：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.11</version>
</dependency>

该问题的核心原因是Spring Boot 3迁移到了Jakarta EE，而springdoc-openapi v1系列仅支持Javax。若不解决，将导致：

• API文档无法自动生成
• Swagger UI无法访问
• 可能触发ClassNotFoundException: javax.servlet.http.HttpServletRequest

解决方案

1. 使用正确的依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.0+</version> <!-- 推荐2.0.2+ -->
</dependency>

重要变化

<artifactId>已从 openapi-ui 变更为 openapi-starter-webmvc-ui

2. 验证版本兼容性

根据Spring Boot版本选择正确的springdoc版本：

Spring Boot 版本	推荐 springdoc 版本
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

最新兼容矩阵参考

官网说明：springdoc.org/compatibility

3. WebFlux项目特殊配置

implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.1.0'
implementation 'org.springframework.boot:spring-boot-starter-webflux'

访问路径：

• OpenAPI JSON: http://localhost:8080/v3/api-docs
• UI界面: http://localhost:8080/swagger-ui.html

WebFlux冲突解决

若同时使用WebMvc和WebFlux，需添加额外配置类：

@Bean
public OpenAPI customOpenAPI() {
  return new OpenAPI().info(new Info().title("API文档"));
}

4. Spring Security配置

启用Spring Security时，需放行相关端点：

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

5. YAML配置选项（可选）

application.yml中自定义路径：

springdoc:
  api-docs:
    path: /api-docs  # JSON文档路径
  swagger-ui:
    path: /swagger-ui.html  # UI访问路径
    enabled: true

无需添加此类配置，默认可用。

完整配置示例

@Configuration
@OpenAPIDefinition
public class SwaggerConfig implements WebMvcConfigurer {

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
      .info(new Info().title("API文档"))
      .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
      .components(new Components()
        .addSecuritySchemes("bearerAuth", 
          new SecurityScheme()
            .type(SecurityScheme.Type.HTTP)
            .scheme("bearer")
            .bearerFormat("JWT")
        )
      );
  }
}

访问路径

添加正确依赖后：

• Swagger UI: http://localhost:8080/swagger-ui/index.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

路径变动

Spring Boot 3中已从 /swagger-ui.html 改为 /swagger-ui/index.html

故障排除

1. 清理浏览器缓存：旧版Swagger UI可能被缓存
2. 验证依赖树：检查是否包含冲突的旧版依赖

   mvn dependency:tree | grep 'springdoc'

3. 检查启动日志：搜索springdoc相关初始化日志
4. Kotlin项目需添加额外依赖：

   <dependency>
     <groupId>com.fasterxml.jackson.module</groupId>
     <artifactId>jackson-module-kotlin</artifactId>
   </dependency>

提示：访问/v3/api-docs验证JSON是否生成，这是UI的基础