SpringDoc OpenAPI 配置-尧图网络

Swagger → SpringDoc 迁移span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-java !-- 移除旧的 Swagger 依赖 -- !-- dependency groupIdio.springfox/groupId artifactIdspringfox-swagger2/artifactId /dependency -- !-- 添加新的 SpringDoc 依赖 -- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId versionspan stylecolor:#b755012.3/spanspan stylecolor:#b75501.0/span/version /dependency /code/span/span配置示例span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javaspan stylecolor:#015692Configuration/span span stylecolor:#015692OpenAPIDefinition/span span stylecolor:#015692public/span span stylecolor:#015692class/span span stylecolor:#b75501SwaggerConfig/span { span stylecolor:#015692Bean/span span stylecolor:#015692public/span OpenAPI span stylecolor:#b75501openAPI/span() { span stylecolor:#b75501OpenAPI/span span stylecolor:#54790dopenAPI/span span stylecolor:#ab5656/span span stylecolor:#015692new/span span stylecolor:#b75501OpenAPI/span(); openAPI.info(span stylecolor:#015692new/span span stylecolor:#b75501Info/span().title(span stylecolor:#54790dAPI 文档/span).version(span stylecolor:#54790d1.0/span)); span stylecolor:#656e77// 配置 Authorization 登录鉴权/span MapString, SecurityScheme map Map.of(span stylecolor:#54790dAuthorization/span, span stylecolor:#015692new/span span stylecolor:#b75501SecurityScheme/span() .type(SecurityScheme.Type.APIKEY) .in(SecurityScheme.In.HEADER) .name(span stylecolor:#54790dAuthorization/span)); openAPI.components(span stylecolor:#015692new/span span stylecolor:#b75501Components/span().securitySchemes(map)); map.keySet().forEach(key - openAPI.addSecurityItem(span stylecolor:#015692new/span span stylecolor:#b75501SecurityRequirement/span().addList(key))); span stylecolor:#015692return/span openAPI; } } /code/span/span注解对应关系Swagger 2.xSpringDoc OpenAPI 3.xApiTagApiOperationOperationApiParamParameterApiModelSchemaApiModelPropertySchema访问地址变更原 Swagger UI 地址http://localhost:8080/swagger-ui.html新 SpringDoc 地址http://localhost:8080/swagger-ui/index.html问题四依赖冲突与安全漏洞修复检测工具使用 IDEA 自带的依赖分析工具必须升级的依赖存在高危漏洞推荐使用OWASP Dependency-Check或Snyk扫描span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-shellmvn dependency-check:check /code/span/span解决依赖冲突的技巧问题Maven 依赖解析采用最短路径优先和第一声明优先原则可能导致旧版本覆盖新版本。解决方案显式声明期望的版本span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javadependencies !-- 显式声明 Spring Framework 版本避免被传递依赖覆盖 -- dependency groupIdorg.springframework/groupId artifactIdspring-core/artifactId versionspan stylecolor:#b755016.1/spanspan stylecolor:#b75501.3/span/version /dependency /dependencies /code/span/span快速检测技巧在 IDEA 的 Maven 依赖树中搜索RELEASESpring 新版本已不使用RELEASE后缀搜索到的基本都是旧版本。问题五URL 尾斜杠匹配策略变更行为变化版本行为Spring Boot 2.x/api/user/get 和 /api/user/get/ 视为同一接口Spring Boot 3.x/api/user/get 和 /api/user/get/ 视为不同接口常见导致尾斜杠的情况Case 1类注解带尾斜杠span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javaspan stylecolor:#015692RequestMapping(/api/user/)/span span stylecolor:#015692public/span span stylecolor:#015692class/span span stylecolor:#b75501UserController/span { span stylecolor:#015692PostMapping(login)/span span stylecolor:#656e77// 实际路径/api/user/login/span } /code/span/spanCase 2空字符串映射span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javaspan stylecolor:#015692RequestMapping(/api/user)/span span stylecolor:#015692public/span span stylecolor:#015692class/span span stylecolor:#b75501UserController/span { span stylecolor:#015692PostMapping()/span span stylecolor:#656e77// 实际路径/api/user/带尾斜杠/span } /code/span/spanCase 3根路径映射span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javaspan stylecolor:#015692PostMapping(/)/span span stylecolor:#656e77// 实际路径/带尾斜杠/span /code/span/span**** 检查方式IDEA Endpoints 工具窗口查看所有端点SpringDoc UI访问 Swagger 页面检查临时解决方案不推荐长期使用span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javaspan stylecolor:#015692import/span org.springframework.context.annotation.Configuration; span stylecolor:#015692import/span org.springframework.web.servlet.config.annotation.PathMatchConfigurer; span stylecolor:#015692import/span org.springframework.web.servlet.config.annotation.WebMvcConfigurer; span stylecolor:#015692Configuration/span span stylecolor:#015692public/span span stylecolor:#015692class/span span stylecolor:#b75501WebConfiguration/span span stylecolor:#015692implements/span span stylecolor:#b75501WebMvcConfigurer/span { span stylecolor:#015692Override/span span stylecolor:#015692public/span span stylecolor:#015692void/span span stylecolor:#b75501configurePathMatch/span(PathMatchConfigurer configurer) { span stylecolor:#656e77// 设置为 true 以忽略尾斜杠恢复旧版本行为/span configurer.setUseTrailingSlashMatch(span stylecolor:#b75501true/span); } } /code/span/span注意__ ·setUseTrailingSlashMatch在 Spring 6.x 后已标记为废弃后续版本将删除。建议逐步修正所有端点去除尾斜杠。根本解决方案修正所有 Controller 的路径映射通知前端团队同步修改调用路径如果有硬编码的 URL全局搜索并修正使用测试确保前后端调用正常问题六Apache POI / EasyExcel 升级背景Apache POI 旧版本 5.0存在多个 CVE 安全漏洞必须升级。推荐方案对于新项目直接使用FastExcelspan stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javadependency groupIdcn.idev.excel/groupId artifactIdfastexcel/artifactId versionspan stylecolor:#b755011.0/spanspan stylecolor:#b75501.0/span/version /dependency /code/span/span对于使用 EasyExcel 的旧项目span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javadependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId versionspan stylecolor:#b755014.0/spanspan stylecolor:#b75501.3/span/version /dependency /code/span/span说明EasyExcel 已不再维护FastExcel 是社区维护的替代方案API 基本兼容。迁移注意事项EasyExcel 跨大版本升级2.x → 4.xAPI 变化较大主要改动1.监听器接口方法签名调整2.部分工具类包路径变更3.自定义转换器需要适配新接口建议参考官方迁移文档EasyExcel官方文档 - 基于Java的Excel处理工具 | Easy Excel 官网问题七JDK 模块化限制--add-opens问题现象某些依赖库使用反射访问 JDK 内部 API在 JDK 9 模块化系统下会报错span stylecolor:#000000span stylebackground-color:#fefef2code classlanguage-javaInaccessibleObjectException: Unable to make field accessible: span stylecolor:#015692module/span java.base does not span stylecolor:#54790dopens java.net/span to unnamed span stylecolor:#015692module/span /code/span/span解决方案在 IDEA 运行配置中添加 VM 参数开启 VM 参数配置默认隐藏