企业官网建设流程全解析

西安中交建设集团网站,网站备案是哪个部门,绍兴公司网站建设,如何办好公司网站Spring Boot 3 JDK 21 项目中从 Swagger 2 升级到 OpenAPI 3.0#xff08;Knife4j#xff09;的完整实践指南——以苍穹外卖项目为例 由于本人使用的 JDK 版本为 21#xff0c;而原苍穹外卖项目基于 Spring Boot 2.x#xff0c;无法直接兼容 JDK 21。因此将项目升级至 Spr…Spring Boot 3 JDK 21 项目中从 Swagger 2 升级到 OpenAPI 3.0Knife4j的完整实践指南——以苍穹外卖项目为例由于本人使用的 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 配置ConfigurationEnableSwagger2publicclassKnife4jConfiguration{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 依赖dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version/dependencydependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependency!-- 可选 Knife4j 增强 --dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion2.0.9/version/dependencySpringFox 的 OpenAPI 3.0 依赖dependencygroupIdio.springfox/groupIdartifactIdspringfox-boot-starter/artifactIdversion3.0.0/version/dependency!-- 可选 Knife4j 增强 --dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.0/version/dependency2. 项目中使用 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.03.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 21dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactIdversion4.3.0/version/dependency3. OpenAPI 3.0 在苍穹外卖项目中的具体实现Spring Boot 3 JDK 21项目背景Spring Boot 3 引入 Jakarta EE 命名空间变更导致传统 SpringFox Swagger 2 无法正常运行。需迁移至支持 OpenAPI 3.0 的新方案。核心依赖dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactIdversion4.3.0/version/dependency配置类ConfigurationpublicclassKnife4jConfiguration{BeanpublicOpenAPIopenApi(){returnnewOpenAPI().info(newInfo().title(苍穹外卖项目接口文档).description(苍穹外卖项目接口文档).version(2.0).contact(newContact().name(mikubob).email(2386782347qq.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 层注解示例RestControllerRequestMapping(/admin/dish)Tag(name菜品相关接口)Slf4jpublicclassDishController{AutowiredprivateDishServicedishService;PostMappingOperation(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 的优秀体验。