news 2026/4/29 0:20:17

Spring Boot 3 + JDK 21 项目中从 Swagger 2 升级到 OpenAPI 3.0（Knife4j）的完整实践指南——以苍穹外卖项目为例

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Spring Boot 3 + JDK 21 项目中从 Swagger 2 升级到 OpenAPI 3.0（Knife4j）的完整实践指南——以苍穹外卖项目为例

Spring Boot 3 + JDK 21 项目中从 Swagger 2 升级到 OpenAPI 3.0（Knife4j）的完整实践指南——以苍穹外卖项目为例

由于本人使用的 JDK 版本为 21，而原苍穹外卖项目基于 Spring Boot 2.x，无法直接兼容 JDK 21。因此将项目升级至 Spring Boot 3.x 后，原本的 Swagger 2.0 不再适用，故将其升级为 OpenAPI 3.0，以适配新环境。

📚 目录（点击跳转对应章节）

1. Swagger 2.0 与 OpenAPI 3.0 的区别
2. 在项目中使用 OpenAPI 3.0 的注意事项
3. OpenAPI 3.0 在苍穹外卖项目中的具体实现

1. Swagger 2.0 与 OpenAPI 3.0 的区别

  • Swagger 2.0 规范文档：https://swagger.io/docs/specification/2-0/basic-structure/
  • OpenAPI 3.0 规范文档：https://swagger.io/docs/specification/basic-structure/

1.1 规范层面的主要差异

1.2 使用方式差异（以 Knife4j 界面为例）

原 Swagger 2.0 界面效果：

OpenAPI 3.0 配置方式：

@ConfigurationpublicclassKnife4jConfiguration{@BeanpublicOpenAPIopenApi(){returnnewOpenAPI().info(newInfo().title("苍穹外卖项目接口文档").description("苍穹外卖项目接口文档").version("2.0").contact(newContact().name("mikubob")));}}

对应的 Swagger 2.0 配置：

@Configuration@EnableSwagger2publicclassKnife4jConfiguration{@BeanpublicDocketopenApi(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(newApiInfoBuilder().title("苍穹外卖项目接口文档").description("苍穹外卖项目接口文档").version("2.0").contact(newContact("mikubob")).build());}}

1.3 接口分组配置差异

分组展示效果：

OpenAPI 3.0 分组配置：

@BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder().group("管理端接口").packagesToScan("com.sky.controller.admin").build();}@BeanpublicGroupedOpenApiuserApi(){returnGroupedOpenApi.builder().group("用户端接口").packagesToScan("com.sky.controller.user").build();}

Swagger 2.0 分组配置：

@BeanpublicDocketadminApi(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("管理端接口").apiInfo(newApiInfoBuilder().title("苍穹外卖项目接口文档").description("苍穹外卖项目接口文档").version("2.0").contact(newContact("mikubob")).build()).select().apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin")).paths(PathSelectors.any()).build();}@BeanpublicDocketuserApi(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("用户端接口").apiInfo(newApiInfoBuilder().title("苍穹外卖项目接口文档").description("苍穹外卖项目接口文档").version("2.0").contact(newContact("mikubob")).build()).select().apis(RequestHandlerSelectors.basePackage("com.sky.controller.user")).paths(PathSelectors.any()).build();}

1.4 依赖配置差异

Swagger 2.0 依赖：

<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><!-- 可选 Knife4j 增强 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version></dependency>

SpringFox 的 OpenAPI 3.0 依赖：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency><!-- 可选 Knife4j 增强 --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.0</version></dependency>

2. 项目中使用 OpenAPI 3.0 的注意事项

2.1 @Tag 与 @Operation 注解使用

OpenAPI 3.0 中name和summary均为必填项：

@Tag(name="用户端-订单接口")@Operation(summary="用户下单")

2.2 旧注解兼容性

若仍使用旧的 Swagger 2 注解，需显式填写字段：

@Api("用户端-订单接口")@ApiOperation("用户下单")

2.3 依赖与 Spring Boot 版本适配（关键避坑）

常见错误：使用 SpringFox 的 OpenAPI 3.0（3.0.0 版本）时，在 Spring Boot 3.x / JDK 17+ 环境下常报java.lang.NoSuchMethodError。
原因：SpringFox 仍依赖旧的javax.servlet包，而 Spring Boot 3 已迁移至jakarta.servlet，导致运行时类版本冲突（编译时方法存在，运行时方法签名不匹配）。

解决办法：

  • 彻底移除所有 SpringFox 相关依赖（springfox-*），避免残留冲突。
  • 推荐使用 springdoc-openapi + Knife4j（完美支持 Spring Boot 3 + JDK 21）：
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency>

3. OpenAPI 3.0 在苍穹外卖项目中的具体实现（Spring Boot 3 + JDK 21）

项目背景

Spring Boot 3 引入 Jakarta EE 命名空间变更，导致传统 SpringFox Swagger 2 无法正常运行。需迁移至支持 OpenAPI 3.0 的新方案。

核心依赖

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency>

配置类

@ConfigurationpublicclassKnife4jConfiguration{@BeanpublicOpenAPIopenApi(){returnnewOpenAPI().info(newInfo().title("苍穹外卖项目接口文档").description("苍穹外卖项目接口文档").version("2.0").contact(newContact().name("mikubob").email("2386782347@qq.com")));}@BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder().group("管理端接口").packagesToScan("com.sky.controller.admin").build();}@BeanpublicGroupedOpenApiuserApi(){returnGroupedOpenApi.builder().group("用户端接口").packagesToScan("com.sky.controller.user").build();}}

静态资源配置（可选）

@OverrideprotectedvoidaddResourceHandlers(ResourceHandlerRegistryregistry){registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}

Controller 层注解示例

@RestController@RequestMapping("/admin/dish")@Tag(name="菜品相关接口")@Slf4jpublicclassDishController{@AutowiredprivateDishServicedishService;@PostMapping@Operation(summary="新增菜品")publicResultsave(@RequestBodyDishDTOdishDTO){log.info("新增菜品：{}",dishDTO);dishService.saveWithFlavor(dishDTO);returnResult.success();}// 其他接口同理添加 @Operation(summary = "...")}

访问方式

启动后访问：http://localhost:8080/doc.html

最终效果

通过上述配置，前端可直接在 Knife4j 界面查看并调试接口，无需阅读后端代码，极大提升联调效率。

小结

使用knife4j-openapi3-jakarta-spring-boot-starter成功实现了 Spring Boot 3 + JDK 21 环境下的现代化 API 文档管理，彻底解决旧版兼容性问题，同时保留了 Knife4j 的优秀体验。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/4/27 13:18:27

解密：毫秒级无网决策，算力如何支撑自动驾驶？

**一、自动驾驶的 “生死时速”&#xff1a;为何必须攻克毫秒级无网决策在自动驾驶领域&#xff0c;“10 毫秒” 是一条隐形的生死线。当车辆以 120km/h 的速度行驶时&#xff0c;每 10 毫秒就会前进 0.33 米&#xff0c;而人类驾驶员的反应延迟通常在 300-500 毫秒之间&#x…

作者头像 李华
网站建设 2026/4/22 18:28:24

不同RFID资产管理系统的功能差异实测：避免选错系统！

在企业管理中&#xff0c;固定资产管理直接影响运营效率与成本控制。传统手工盘点模式因效率低、易出错等问题&#xff0c;逐渐被RFID&#xff08;射频识别&#xff09;技术取代。然而&#xff0c;不同厂商的RFID资产管理系统在功能设计、技术架构、应用场景适配性等方面存在显…

作者头像 李华
网站建设 2026/4/20 13:50:47

机房U位100%管理不是梦！首码资产管理系统客户实测报告

摘要&#xff1a;面对数据中心U位资产管理的世纪难题&#xff0c;我们通过部署首码U位资产管理系统&#xff0c;在实测周期内实现了从混乱到100%准确率的惊人跨越。本文将完整复盘这次技术实践的全过程与关键数据。一、前言&#xff1a;一个运维的“老大难”问题在数据中心日常…

作者头像 李华
网站建设 2026/4/28 21:37:55

如何选择专业的工程照明公司？

于专业照明范畴内&#xff0c;工程照明公司的挑选与项目的终极成效、长久能耗以及维护成本直接关联 &#xff0c;这类公司不但供给产品 &#xff0c;更得拥有从方案设计 、产品定制直到安装支持的整个链条服务能力 。市场里活跃着诸多工程照明企业 &#xff0c;它们的技术路线 …

作者头像 李华
网站建设 2026/4/24 3:52:02

哈希函数特性总结

作者&#xff1a;chen-trueqq.com 仅供学习交流&#xff0c;如有错误恳请指出&#xff01; 哈希函数&#xff08;Hash function&#xff09;&#xff0c;又称哈希算法、散列函数、杂凑函数、摘要算法等&#xff0c;是一种将任意长度的输入数据M&#xff0c;通过一个确定性的映…

作者头像 李华