Spring MVC下Springfox升级3.0.0后Swagger启动报错如何解决

你遇到的NoClassDefFoundError报错是两个核心问题导致的：

• 单独引入的io.swagger.core.v3:swagger-annotations版本和Springfox 3.0.0内部依赖的swagger注解版本不兼容，触发类初始化异常
• Springfox 3.0.0对Spring MVC的适配需要额外的配置项，缺少对应配置会导致documentationPluginsBootstrapper启动失败

第一步：修正Maven依赖 #

首先删除现有配置中所有和swagger、springfox相关的依赖，替换为以下配置：

<!-- 统一管理Springfox版本 -->
<properties>
    <springfox.version>3.0.0</springfox.version>
</properties>

<dependencies>
    <!-- Springfox 3.0.0核心依赖，包含swagger2、swagger-ui和适配的注解包 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <!-- 不要单独引入swagger-annotations，Springfox会自动引入兼容版本 -->
</dependencies>

如果是Spring Boot项目，直接使用官方starter更简便：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

第二步：添加Swagger配置类 #

在Spring MVC的配置扫描路径下新增配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        // 3.0.0默认使用OAS_30规范，不要使用2.x版本的SWAGGER_2
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 替换为实际项目的Controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.your.project.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("项目接口文档说明")
                .version("1.0")
                .build();
    }
}

第三步：Spring MVC资源映射配置 #

如果是纯Spring MVC（非Spring Boot）项目，需要在MVC配置类中添加静态资源映射，否则无法打开swagger-ui页面：

import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

第四步：兼容配置（启动仍报错时添加） #

如果完成以上配置后还是启动失败，在Spring配置文件中添加以下配置，解决Spring版本和Springfox路径匹配策略不兼容的问题：
application.properties格式：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

如果是xml配置的Spring MVC，添加对应属性配置即可。

配置全部完成后启动项目，访问http://{项目地址}:{端口}/{项目上下文路径}/swagger-ui/index.html即可查看接口文档。

内容的提问来源于stack exchange，提问作者Doctor Who