当前位置：首页 > news >正文

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

news 2026/8/31 15:02:40

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 = "...")}