Spring Boot WebSocket与SpringDoc Swagger UI冲突：报错“Can Upgrade only to WebSocket”

问题描述 #

Spring Boot应用中，WebSocket端点配置为/*（匹配所有路径），同时集成SpringDoc OpenAPI暴露Swagger UI。访问/swagger-ui/index.html时出现错误提示：Can 'Upgrade' only to 'WebSocket'，原因是WebSocket拦截了Swagger UI的HTTP请求，导致请求被错误地当作WebSocket升级请求处理。

解决方案 #

无需修改WebSocket的/*端点，只需在WebSocket配置中排除Swagger相关的路径，让这些请求交由Spring MVC正常处理即可。

修改WebSocketConfig类，添加excludePathPatterns方法排除Swagger相关路径：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(new MyWebSocketHandler(), "/*")
                .setAllowedOrigins("*")
                // 排除Swagger UI及OpenAPI文档的相关路径
                .excludePathPatterns(
                    "/swagger-ui/**",
                    "/v3/api-docs/**",
                    "/swagger-resources/**",
                    "/webjars/**"
                );
    }
}

说明 #

• excludePathPatterns方法用于指定WebSocket handler不处理的路径，将Swagger的静态资源、API文档元数据等路径全部排除后，这些请求会被Spring MVC正确处理，不再触发WebSocket的升级逻辑。
• 该方案保留了WebSocket的/*端点配置，同时解决了与Swagger UI的路径冲突问题，无需调整Swagger的默认路径或重定向规则。

内容的提问来源于stack exchange，提问作者Michał Zawadzki