mp-java/docs/SWAGGER_FIX_GUIDE.md

Springfox 兼容性问题修复指南

问题描述

Spring Boot 应用启动时出现以下错误：

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

问题原因

• Spring Boot 2.6+ 默认使用 PathPatternMatcher 替代 AntPathMatcher
• Springfox 3.0.0 仍然依赖旧的 AntPathMatcher，导致兼容性问题

解决方案

方案1：配置兼容性（临时方案）

在 application.yml 中添加：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

方案2：升级到 SpringDoc OpenAPI（推荐）

1. 更新 pom.xml 依赖

<!-- 替换 Springfox -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

<!-- 更新 Knife4j -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

2. 更新 SwaggerConfig.java

@Configuration
public class SwaggerConfig {
    @Resource
    private ConfigProperties config;

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(config.getSwaggerTitle())
                        .description(config.getSwaggerDescription())
                        .version(config.getSwaggerVersion())
                        .contact(new Contact()
                                .name("科技小王子")
                                .url("https://www.gxwebsoft.com")
                                .email("170083662@qq.com")))
                .components(new Components()
                        .addSecuritySchemes("Authorization", 
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")))
                .addSecurityItem(new SecurityRequirement().addList("Authorization"));
    }
}

3. 重新编译项目

mvn clean package -DskipTests

4. 运行应用

java -jar target/your-app.jar

验证修复

1. 应用启动无错误
2. 访问 Swagger UI：http://localhost:9200/swagger-ui.html
3. 访问 API 文档：http://localhost:9200/v3/api-docs

注意事项

• SpringDoc OpenAPI 使用不同的注解和配置方式
• 可能需要更新 Controller 中的 Swagger 注解
• Knife4j 4.x 版本与 SpringDoc 兼容

状态

✅ 配置文件已修改 ✅ 依赖已更新 ✅ SwaggerConfig 已重写 ⏳ 需要重新编译项目以生效