Spring Boot 2.7.4整合Springfox 3.0.0与Actuator启动异常问题

问题背景 #

将Spring Boot项目升级至2.7.4版本，同步升级Springfox到3.0.0后，启动时抛出异常：

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

尝试添加配置spring.mvc.pathmatch.matching-strategy=ant-path-matcher后问题未解决，发现冲突由Spring Actuator引发——设置management.server.port=8082（自定义管理端口）可临时解决，但希望保留默认服务器端口，需明确冲突原因及无侵入解决方案。

冲突原因 #

Spring Boot 2.6+ 默认采用PathPatternMatcher作为路径匹配策略，而Springfox 3.0.0未完全适配该新匹配器。当Spring Actuator与应用共享默认端口时，Actuator会注册一系列端点路径，Springfox在扫描所有请求映射时，其内部逻辑依赖旧的AntPathMatcher，处理Actuator端点路径时因匹配器不兼容，导致获取路径元数据时触发空指针异常，最终导致documentationPluginsBootstrapper bean初始化失败。

解决方案（无需修改管理端口） #

方案1：适配路径匹配逻辑 #

在Swagger配置类中添加自定义的WebMvcEndpointHandlerMapping bean，修复Springfox与Actuator的路径匹配冲突：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.io"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList<>();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping);
    }

    private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
    }
}

方案2：排除Actuator端点扫描 #

修改Swagger的Docket配置，直接排除Actuator的端点路径，避免Springfox处理这些路径：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.io"))
                // 排除所有/actuator开头的路径
                .paths(PathSelectors.regex("^(?!/actuator).*$"))
                .build();
    }
}

方案3：迁移至SpringDoc OpenAPI（推荐） #

由于Springfox已停止官方维护，无法适配后续Spring Boot版本，推荐迁移至SpringDoc OpenAPI，它完全兼容Spring Boot 2.6+版本，使用方式与Springfox类似，且无需处理此类冲突。

内容的提问来源于stack exchange，提问作者ima.technophyle