Spring Boot 3中启用Swagger API端点遇404的问题排查

核心原因 #

Springfox 3.0.0已于2020年停止维护，完全不兼容Spring Boot 3.x版本：

• Spring Boot 3基于Spring Framework 6，底层从Java EE迁移到Jakarta EE规范，Springfox未适配这一核心变化，导致其端点无法被Spring Boot 3正确注册，因此访问/v2/api-docs会返回404。
• 你尝试降级Spring Boot到2.4.0时出现的Unsupported class file major version 61错误，是因为Spring Boot 2.4.x最高仅支持Java 15，而Java 17生成的类文件版本为61，旧版框架无法识别。

解决方案：改用Springdoc OpenAPI #

Springdoc OpenAPI是Spring Boot 3官方推荐的API文档工具，完全兼容Jakarta EE和Java 17，替代Springfox即可解决问题。

步骤1：替换依赖 #

移除POM中的Springfox依赖，添加Springdoc的starter依赖：

<!-- 移除原有Springfox依赖 -->
<!-- <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency> -->

<!-- 添加Springdoc OpenAPI依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

步骤2：移除无用配置 #

删除原有的SpringFoxConfig配置类，Springdoc默认自动启用API文档功能，无需额外配置。

步骤3：验证访问 #

启动应用后，访问以下端点：

• Swagger UI界面：http://localhost:8080/swagger-ui.html
• OpenAPI 3.0格式的API文档：http://localhost:8080/v3/api-docs

自定义配置（可选） #

如果需要自定义文档信息（如标题、版本、描述），可以添加如下配置类：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Hello World API")
                        .version("1.0")
                        .description("Spring Boot 3 + Springdoc OpenAPI示例"));
    }
}

内容的提问来源于stack exchange，提问作者Sergey Zolotarev