Springfox 3 集成与 Spring Boot 2.6 兼容性

相关概念：spring-boot

如果项目仍在使用 Springfox，那最容易踩到的一类坑不是“怎么接入”，而是“版本组合到底能不能一起工作”。

Springfox 3 的基本接入

在 Springfox 3 时代，常见接入方式已经变成 starter 依赖：

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

一个最小配置通常就是声明一个 Docket：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example.consumer.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

和旧版本相比的一个变化

这代接入里，@EnableSwagger2 这种旧入口已经不再是重点，starter 方式更自然。

真正的坑：Spring Boot 2.6

很多项目不是“配错了”，而是升级到 Spring Boot 2.6.x 之后突然报：

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

这个问题的根因不在业务代码，而在于：

• Spring Boot 2.6 调整了 MVC 路径匹配策略
• Springfox 3 对这个变化兼容得并不好

止血方案

如果短期内还不能迁移文档方案，可以先把匹配策略切回旧行为：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

判断

对于存量系统，这个配置通常能较快恢复可用状态。

但如果是新项目，通常不再建议继续押 Springfox，而会优先考虑更现代、兼容性更稳的 OpenAPI 方案。

结论

这类问题很典型地说明了一件事：

文档工具看起来是外围组件，但一旦和框架内部机制耦合太深，版本升级时一样会卡核心流程。