Swagger2页面401未授权问题：已配置认证绕过仍异常

阿华AIGC实验室

2026-5-22

解决Swagger UI绕过认证后仍返回异常的问题

我之前也碰到过一模一样的问题——只放过/swagger-ui.html根本不够！Swagger UI页面可不是只靠这一个HTML文件就能跑起来的，它还依赖一堆静态资源和接口，这些路径如果没一起绕过认证，照样会被拦截，最后页面就会显示异常。

给你梳理几个关键问题和解决办法：

遗漏了Swagger相关的其他资源路径
你得把Swagger用到的所有路径都加入绕过列表，包括：
- /swagger-resources/**：Swagger的资源配置接口
- /v2/api-docs：接口文档的数据源接口
- /webjars/**：Swagger UI用到的前端静态资源（比如js、css、图标）

修改过滤逻辑，补充路径并提前返回
把这些路径都加进判断里，还要记得加return，避免绕过之后还执行后续的认证逻辑：

String resourcePath = new UrlPathHelper().getPathWithinApplication(httpRequest);
// 匹配所有Swagger相关路径
if (resourcePath.equalsIgnoreCase("/swagger-ui.html") 
    || resourcePath.startsWith("/swagger-resources")
    || resourcePath.startsWith("/v2/api-docs")
    || resourcePath.startsWith("/webjars")) {
    filterChain.doFilter(request, response);
    return; // 必须加return，终止当前过滤器的后续逻辑
}
// 你的其他认证逻辑代码

检查过滤器执行顺序
如果你的认证过滤器优先级太高，在Spring MVC的资源处理过滤器之前执行，也会导致资源加载失败。可以给你的认证过滤器加上@Order注解，设置一个较高的数值（比如@Order(100)），让它在资源处理过滤器之后运行。
验证路径匹配的准确性
调试时可以把resourcePath打印出来，看看实际请求的路径是不是和你判断的一致。比如如果项目有上下文路径（比如/my-project），那实际路径会是/my-project/swagger-ui.html，这时候你的判断就会失效。这种情况可以用request.getRequestURI()获取完整路径，或者先去掉上下文路径再做匹配。