SpringDoc OpenAPI 2.8.4+ 版本中Swagger UI授权功能失效问题解析

问题背景

在使用SpringDoc OpenAPI库时，从2.8.4版本开始，Swagger UI中的授权功能出现了异常。具体表现为：当用户点击"Authorize"按钮尝试登录时，系统会显示一个空白错误页面，状态码为999，而不是预期的授权流程。

问题根源

这个问题的根本原因是SpringDoc OpenAPI在2.8.4版本中引入了一个重要的变更，目的是为了统一WebFlux和WebMvc两种技术栈下的Swagger UI路径前缀。这个变更导致了授权重定向URL的格式发生了变化，但相关文档并未充分说明这一变化。

技术细节

在SpringDoc OpenAPI 2.8.4之前的版本中，Swagger UI的OAuth2重定向URL默认包含"webjars"前缀，格式类似于： https://host:port/context-path/webjars/swagger-ui/oauth2-redirect.html

而从2.8.4版本开始，这个URL格式被简化为： https://host:port/context-path/swagger-ui/oauth2-redirect.html

这一变化影响了OAuth2授权服务器的配置，如果授权服务器仍然配置了包含"webjars"前缀的回调URL，就会导致授权流程中断。

解决方案

要解决这个问题，开发者需要调整授权服务器的配置，移除回调URL中的"webjars"前缀。具体步骤如下：

1. 在授权服务器配置中，找到与Swagger UI集成的相关配置
2. 将包含"webjars"前缀的重定向URL修改为新的格式
3. 确保所有相关的安全配置都使用一致的重定向URL格式

最佳实践

为了避免类似问题，建议开发者在升级SpringDoc OpenAPI版本时：

1. 仔细阅读版本变更日志，特别是涉及路径配置的变更
2. 在测试环境中先验证授权流程是否正常工作
3. 考虑使用相对路径而非绝对路径来配置重定向URL，提高配置的灵活性

总结

SpringDoc OpenAPI 2.8.4+版本对Swagger UI路径前缀的标准化是一个积极的改进，虽然短期内可能导致一些集成问题，但从长远来看有助于统一不同技术栈下的行为。开发者只需要相应调整授权服务器的配置即可解决授权功能失效的问题。

对于使用Spring Security OAuth2的开发者来说，理解这一变化也有助于更好地掌握OAuth2授权流程中重定向URL的配置原理，提升系统安全性。