springfox-swagger2迁移到springdoc-openapi？

在Spring Boot 3.4环境中，将`springfox-swagger2`迁移到`springdoc-openapi`是一个常见的需求。以下是详细的迁移指导和注意事项。 ### 迁移背景 随着Spring Boot升级到3.x版本，其底层依赖从`javax.*`迁移到了`jakarta.*`命名空间[^2]。由于`springfox-swagger2`仍然基于旧的`javax.*`包结构，这导致了与Spring Boot 3.x环境的不兼容问题。因此，推荐使用`springdoc-openapi`作为替代方案，因为它完全支持新的`jakarta.*`命名空间，并且提供了更好的性能和维护性。 --- ### 迁移步骤 #### 1. 移除旧依赖 首先需要彻底删除原有的`springfox-swagger2`相关依赖。通常这些依赖可能存在于项目的`pom.xml`文件中： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>...</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>...</version> </dependency> ``` 确保清理掉所有与`springfox`相关的条目。 --- #### 2. 添加新依赖 接着引入`springdoc-openapi`的相关依赖。对于标准Web MVC应用，可以添加以下内容： ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.0.4</version> <!-- 使用最新稳定版本 --> </dependency> ``` 如果是响应式应用，则需改用对应的WebFlux依赖： ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webflux-ui</artifactId> <version>2.0.4</version> </dependency> ``` --- #### 3. 配置调整 大多数情况下，`springdoc-openapi`能够零配置运行。然而，为了满足具体业务需求，可以通过Java配置类或YAML/Properties文件进行进一步定制。 ##### 示例：全局信息配置 通过创建一个配置类来指定API文档的基础信息： ```java import io.swagger.v3.oas.models.info.Info; import org.springdoc.core.models.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class OpenApiConfig { @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("Public APIs") .pathsToMatch("/api/**") // 只包含路径前缀为 /api 的接口 .build(); } @Bean public Info customInfo() { return new Info() .title("My Application API Documentation") .description("This is the official API documentation for my application.") .version("1.0.0"); } } ``` 上述代码定义了一个名为`Public APIs`的分组，并指定了匹配规则和基础元数据[^3]。 --- #### 4. 处理常见问题 ##### （1）解决`javax.servlet.http.HttpServletRequest`缺失问题 由于Spring Boot 3.x切换到了Jakarta EE规范，可能会遇到类似以下错误： ``` Type javax.servlet.http.HttpServletRequest not present ``` 这是因为在新的环境中，应该使用`jakarta.servlet.http.HttpServletRequest`代替原来的`javax.servlet.http.HttpServletRequest`。确认项目中的所有代码均已同步更新至Jakarta命名空间[^4]。 ##### （2）Swagger UI访问路径 默认情况下，`springdoc-openapi`会在以下路径暴露Swagger UI界面： - **UI页面**: `/swagger-ui/index.html` 或 `/swagger-ui/` - **JSON/YAML文档**: `/v3/api-docs` 如果需要更改默认路径，可以在`application.yml`中设置： ```yaml springdoc: swagger-ui: path: /custom-swagger-ui ``` --- #### 5. 测试验证 完成上述改动后，重新构建并启动应用程序。打开浏览器访问`http://localhost:<port>/swagger-ui/`，检查是否正常显示API文档页面。同时测试各个接口调用情况，确保功能未受影响。 --- ### 性能优化建议 针对大型项目，可以考虑以下几个方面的优化： - **延迟加载**: 将API文档生成过程推迟到首次访问时触发，从而加快应用启动速度。 - **缓存机制**: 利用内存级缓存存储已生成的文档内容，减少重复计算开销。 --- ### 结论 通过采用`springdoc-openapi`替换传统的`springfox-swagger2`，不仅可以有效规避Spring Boot 3.x带来的兼容性挑战，还能够享受到更加现代化的功能特性和支持[^1]。整个迁移过程虽然涉及一定工作量，但从长远来看无疑是一次值得的投资。 ---