Sirius Web项目Swagger UI页面不可访问问题分析

Sirius Web项目Swagger UI页面不可访问问题分析

sirius-web Reusable frontend and backend components for Sirius Web 项目地址: https://gitcode.com/gh_mirrors/si/sirius-web

问题背景

在Sirius Web项目中，随着Spring Boot升级到3.4.1版本并引入FrontendRouterConfiguration配置后，开发人员发现原本可用的Swagger UI页面(http://localhost:8080/swagger-ui/index.html)和OpenAPI文档(http://localhost:8080/v3/api-docs/rest-apis)变得无法正常访问。

现象表现

当访问Swagger UI页面时，系统不再显示Sirius Web项目的API文档，而是默认显示Petstore示例。同时，直接访问OpenAPI文档端点时也无法获取到预期的JSON格式API描述文件。

根本原因分析

经过排查，问题源于新引入的FrontendRouterConfiguration配置类。该类负责前端路由配置，但未将Swagger UI和OpenAPI相关的路径("/v3/api-docs/**")包含在允许访问的路径列表中。这导致Spring Security拦截了对这些端点的请求，使得Swagger UI无法正常获取API文档信息。

技术细节

1. Spring Boot 3.4.1变更：新版本对安全配置和路由处理有细微调整，需要显式配置Swagger相关路径

2. FrontendRouterConfiguration影响：该配置接管了前端路由处理，但未考虑API文档展示的需求

3. Swagger UI工作机制：Swagger UI需要能够访问/v3/api-docs端点来获取API定义，然后才能正确渲染文档界面

解决方案

修复此问题的方法相对简单，只需在安全配置中添加对Swagger相关路径的放行：

1. 将"/v3/api-docs/**"路径添加到允许访问的路径列表中
2. 确保"/swagger-ui/**"路径也被包含在内
3. 检查其他可能需要的Swagger相关路径

最佳实践建议

1. API文档路径标准化：建议为API文档路径建立统一的前缀，便于管理和维护

2. 环境区分：在生产环境中应考虑禁用Swagger UI，仅限开发环境使用

3. 版本兼容性检查：升级Spring Boot版本时，应全面测试API文档功能

4. 安全配置审查：任何路由和安全配置变更都应评估对辅助功能(如API文档)的影响

总结

这个问题展示了在Web应用开发中，安全配置与辅助功能之间需要保持平衡。特别是在框架升级和引入新配置时，开发团队需要全面评估变更对系统各功能模块的影响。通过合理配置，可以确保开发工具链的完整性和可用性，同时不牺牲系统的安全性。

sirius-web Reusable frontend and backend components for Sirius Web 项目地址: https://gitcode.com/gh_mirrors/si/sirius-web