从Springfox到SpringDoc OpenAPI的完整迁移指南

更新时间：2025年08月11日 09:29:39 作者：码农阿豪@新空间

在SpringBoot项目中,API文档是前后端协作的重要桥梁,长期以来,Springfox一直是Java生态中最流行的API文档工具之一,但随着SpringBoot版本的迭代,特别是2.6+版本后,Springfox的兼容性问题逐渐显现,所以本文介绍了从Springfox到SpringDoc OpenAPI的完整迁移指南

引言

在Spring Boot项目中，API文档是前后端协作的重要桥梁。长期以来，Springfox（Swagger）一直是Java生态中最流行的API文档工具之一。但随着Spring Boot版本的迭代，特别是2.6+版本后，Springfox的兼容性问题逐渐显现，导致许多开发者转向更现代的替代方案——SpringDoc OpenAPI。

本文将详细介绍：

Springfox的常见问题（如NullPointerException）
为何选择SpringDoc OpenAPI
完整迁移步骤（含代码示例）
最佳实践与优化建议

1. Springfox的常见问题

1.1 典型错误分析

在Spring Boot 2.6+中，启动时可能遇到以下错误：

Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
...
Caused by: java.lang.NullPointerException: null
    at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:112)

原因：

Spring Boot 2.6+默认使用PathPattern进行路径匹配，而Springfox 2.x仅支持传统的AntPathMatcher，导致空指针异常。

1.2 临时解决方案

在application.properties中强制使用AntPathMatcher：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

但这只是权宜之计，长期推荐迁移到SpringDoc。

2. 为何选择SpringDoc OpenAPI？

特性	Springfox	SpringDoc
兼容性	仅支持Spring Boot <2.6	完美支持Spring Boot 2.6+
注解标准	Swagger 2.0	OpenAPI 3.0
自动发现机制	有限	强大
JWT支持	需手动配置	内置支持
社区活跃度	维护停滞	持续更新

3. 完整迁移步骤

3.1 移除Springfox依赖

在pom.xml中删除所有Springfox相关依赖：

<!-- 移除以下依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.2 添加SpringDoc依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

3.3 替换配置类

将原有的SwaggerConfig替换为OpenApiConfig：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("手机号碰撞系统API")
                        .version("v1.0.0")
                        .contact(new Contact()
                                .name("开发团队")
                                .url("https://github.com/your-repo")
                                .email("dev@example.com")))
                .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
                .components(new Components()
                        .addSecuritySchemes("BearerAuth", 
                            new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));
    }
}

3.4 修改启动类

移除@EnableSwagger2注解：

@SpringBootApplication
public class AppApplication {
    public static void main(String[] args) {
        SpringApplication.run(AppApplication.class, args);
    }
}

3.5 更新Controller注解

替换Swagger注解为OpenAPI 3.0标准：

@RestController
@Tag(name = "手机号管理", description = "手机号碰撞相关API")
@RequestMapping("/api/phones")
public class PhoneController {

    @Operation(summary = "获取手机号信息", description = "根据ID查询手机号")
    @GetMapping("/{id}")
    public ResponseEntity<Phone> getPhone(
            @Parameter(description = "手机号ID", required = true)
            @PathVariable Long id) {
        // 业务逻辑
    }
}

4. 高级配置与优化

4.1 分组API文档

@Bean
@GroupedOpenApi
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
            .group("用户管理API")
            .pathsToMatch("/api/user/")
            .build();
}

4.2 自定义Swagger UI

在application.properties中配置：

springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=alpha
springdoc.swagger-ui.tagsSorter=alpha
springdoc.swagger-ui.doc-expansion=none

4.3 隐藏特定接口

使用@Hidden注解：

@Hidden
@GetMapping("/internal")
public String internalApi() {
    return "内部接口";
}

5. 迁移后的效果验证

访问Swagger UI：
http://localhost:8080/swagger-ui.html

查看OpenAPI JSON：
http://localhost:8080/v3/api-docs

验证JWT支持：
在Swagger UI中点击"Authorize"按钮，输入Bearer Token测试。

6. 常见问题解决

6.1 文档不显示某些接口

检查是否有@RequestMapping或@Operation注解
确保Controller在Spring扫描路径内

6.2 页面加载缓慢

清理浏览器缓存
禁用SpringDoc的缓存（开发环境）：

springdoc.cache.disabled=true

结语

通过本文，你已完成了从Springfox到SpringDoc的完整迁移。SpringDoc不仅解决了兼容性问题，还提供了更强大的功能。建议所有新项目直接采用SpringDoc，老项目逐步迁移。

最终优势：

✅ 更好的兼容性
✅ 更简洁的配置
✅ 支持OpenAPI 3.0标准
✅ 活跃的社区维护

以上就是从Springfox到SpringDoc OpenAPI的完整迁移指南的详细内容，更多关于Springfox到SpringDoc OpenAPI迁移的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

SpringBoot使用Redisson实现延迟执行的完整示例
这篇文章主要介绍了SpringBoot使用Redisson实现延迟执行的完整示例,文中通过代码示例讲解的非常详细,对大家的学习或工作有一定的帮助,需要的朋友可以参考下
2024-06-06
Java简单使用EasyExcel操作读写excel的步骤与要点
相信现在很多搞后端的同学大部分做的都是后台管理系统,那么管理系统就肯定免不了Excel的导出导入功能,下面这篇文章主要给大家介绍了关于Java简单使用EasyExcel操作读写excel的步骤与要点,需要的朋友可以参考下
2022-09-09
springboot项目如何部署到服务器
这篇文章主要介绍了springboot项目如何部署到服务器问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2024-05-05
SpringBoot如何在运行时动态添加数据源
这篇文章主要介绍了SpringBoot如何在运行时动态添加数据源,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2019-10-10
Java与JavaScript自动化测试Selenium使用详解
这篇文章主要介绍了Java与JavaScript自动化测试Selenium的使用,Selenium是一个用于Web应用程序测试的工具,Selenium测试直接运行在浏览器中,就像真正的用户在操作一样,需要的朋友可以参考下
2025-05-05
Java异常处理try catch的基本用法
try就像一个网，把try{}里面的代码所抛出的异常都网住，然后把异常交给catch{}里面的代码去处理。最后执行finally之中的代码。无论try中代码有没有异常，也无论catch是否将异常捕获到，finally中的代码都一定会被执行。
2021-12-12
解决java编译错误:程序包不存在的问题
出错：Error:(3, 27) java: 程序包com.aliyun.odps.udf不存在，遇到这样的错误问题如何解决呢，下面小编给大家带来了java编译错误:程序包不存在的问题及解决方法，感兴趣的朋友一起看看吧
2023-05-05
使用纯java config来配置spring mvc方式
这篇文章主要介绍了使用纯java config来配置spring mvc方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-11-11
Java之通过OutputStream写入文件与文件复制问题
这篇文章主要介绍了Java之通过OutputStream写入文件与文件复制问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2023-04-04
maven中的maven-antrun-plugin插件示例详解
maven-antrun-plugin 是 Maven 生态中一个强大的工具,尤其适合需要复用 Ant 脚本或实现复杂构建逻辑的场景,然而,过度使用可能导致构建脚本复杂化,建议权衡利弊后合理使用,这篇文章主要介绍了maven中的maven-antrun-plugin插件详解,需要的朋友可以参考下
2025-06-06