SpringDoc OpenAPI 中 Swagger UI 多路径访问问题的分析与解决

问题背景

在 SpringDoc OpenAPI 项目中，当通过不同的上下文路径访问 Swagger UI 时，会出现初始化失败的问题。这个问题特别容易在反向代理场景下复现，例如当应用同时通过直接访问和代理访问两种方式提供服务时。

问题现象

开发人员发现，当通过以下两种顺序访问 Swagger UI 时会出现问题：

1. 先通过反向代理访问（如 http://localhost:80/service/**），再直接访问后端服务（如 http://localhost:8080/**）时，第二次访问会失败
2. 先直接访问后端服务，再通过反向代理访问时，同样第二次访问会失败

根本原因分析

经过深入排查，发现问题出在 SwaggerIndexPageTransformer 类的实现上。这个类会初始化一个单例的 SwaggerUiConfigParameters，并通过 swaggerWelcomeCommon.buildFromCurrentContextPath(request) 方法来设置 configUrl。

关键问题在于：

1. 第一次请求时的上下文路径会被缓存
2. 后续请求即使使用不同的上下文路径，仍然会使用缓存的配置
3. 浏览器最终会尝试从一个错误的 URL 加载配置

并发问题

在初步修复后，测试发现还存在并发场景下的问题。当多个请求同时使用不同的上下文路径访问时：

1. SwaggerIndexPageTransformer.swaggerWelcomeCommon 被多个请求共享
2. 每个请求都会修改这个共享对象
3. 导致返回的配置信息可能混合了不同请求的路径信息

解决方案

项目维护者经过多次迭代，最终通过以下方式解决了问题：

1. 移除了对 SwaggerUiConfigParameters 的单例依赖
2. 确保每次请求都能独立计算正确的路径
3. 解决了并发场景下的路径混淆问题

技术要点

这个问题的解决涉及到几个重要的技术点：

1. 上下文路径处理：正确处理反向代理添加的前缀
2. 线程安全：确保共享对象在多线程环境下的正确性
3. 配置隔离：保证每个请求都能获取到基于自己上下文路径的正确配置

最佳实践

对于使用 SpringDoc OpenAPI 的开发者，建议：

1. 在反向代理场景下，确保正确配置 X-Forwarded-Prefix 头部
2. 及时更新到包含此修复的版本
3. 在复杂部署环境下，充分测试不同访问路径下的 Swagger UI 行为

这个问题及其解决方案展示了在实际开发中如何处理路径重写和并发访问的常见挑战，为类似场景提供了有价值的参考。