确保增加 swagger 依赖
pom.xml
<!-- Swagger --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version></dependency>在浏览器打开：http://localhost:8080/swagger-ui/index.html，出现空白页
再点击刷新，显示该网页无法正常远行
控制台上输出 401 状态
根据浏览器控制台的错误信息 "Failed to load resource: the server responded with a status of 401 ()"，这表明您的请求被服务器拒绝，原因是身份验证失败 (401 Unauthorized)。
路径被拦截或安全配置
-
安全框架拦截：若项目使用了 Spring Security，需放行 Swagger 相关路径：
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll() // 放行路径.anyRequest().authenticated();}
}-
检查过滤器/拦截器：自定义过滤器或拦截器可能阻止访问，需排除 Swagger 路径。
原来项目中的拦截器：
WebConfig.java
package com.weiyu.config;import com.weiyu.interceptors.LoginInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** Spring MVC 配置类*/
@Configuration
public class WebConfig implements WebMvcConfigurer {@Autowiredprivate LoginInterceptor loginInterceptor;/*** 增加拦截器，将拦截器添加到 Spring MVC** @param registry 拦截器对象*/@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 增加登录拦截器，默认拦截所有的请求registry.addInterceptor(loginInterceptor)// 请求白名单，不拦截的请求.excludePathPatterns(// 登录接口"/account/login",// 注册接口"/user/register");}
}
将 swagger 增加进白名单
package com.weiyu.config;import com.weiyu.interceptors.LoginInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** Spring MVC 配置类*/
@Configuration
public class WebConfig implements WebMvcConfigurer {@Autowiredprivate LoginInterceptor loginInterceptor;/*** 增加拦截器，将拦截器添加到 Spring MVC** @param registry 拦截器对象*/@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 增加登录拦截器，默认拦截所有的请求registry.addInterceptor(loginInterceptor)// 请求白名单，不拦截的请求.excludePathPatterns(// 登录接口"/account/login",// 注册接口"/user/register",// Swagger"/swagger-ui/**","/swagger-resources/**","/v3/api-docs/**","/webjars/**","/swagger-ui.html");}
}
重启应用，访问效果：
如果你无法访问 http://localhost:8080/swagger-ui.html，可能是以下原因导致的。请按步骤排查：
1. 服务未运行或端口错误
-
检查服务是否启动：确保你的 Spring Boot 应用已成功启动（查看控制台日志，确认无报错）。
-
验证端口：检查应用是否运行在
8080端口（默认端口）。若端口被修改（如application.properties中设置server.port=9090），需访问http://localhost:9090/swagger-ui.html。
2. Swagger 依赖未正确配置
-
确认依赖：确保项目中已添加 Swagger 依赖（根据版本选择）：
-
Springdoc (OpenAPI 3)（推荐）：
xml
复制
下载
运行
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version> <!-- 检查最新版本 --> </dependency>
-
Springfox (Swagger 2)（旧版）：
xml
复制
下载
运行
<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version> </dependency>
-
-
清理构建：更新依赖后执行
mvn clean install或gradle clean build。
3. 路径被拦截或安全配置
-
安全框架拦截：若项目使用了 Spring Security，需放行 Swagger 相关路径：
java
复制
下载
@Configuration public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll() // 放行路径.anyRequest().authenticated();} } -
检查过滤器：自定义过滤器或拦截器可能阻止访问，需排除 Swagger 路径。
4. 上下文路径（Context Path）
-
若设置了
server.servlet.context-path（如server.servlet.context-path=/api），Swagger 的路径会变为：text
复制
下载
http://localhost:8080/api/swagger-ui.html
5. 访问备用路径
-
Springdoc 的备用路径：
-
http://localhost:8080/swagger-ui/index.html -
http://localhost:8080/swagger-ui/
-
-
Springfox 的路径：
-
http://localhost:8080/swagger-ui/（注意结尾斜杠）
-
6. 检查 Swagger 配置类
-
Springfox 需要配置类（旧版）：
java
复制
下载
@Configuration @EnableSwagger2 public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();} } -
Springdoc 无需配置（默认启用）。
7. 浏览器缓存或代理问题
-
清除缓存：使用 Ctrl + Shift + R（Windows）或 Cmd + Shift + R（Mac）强制刷新页面。
-
关闭代理：浏览器代理或 VPN 可能导致 localhost 访问异常。
8. 验证 API 文档 JSON 是否生成
访问以下路径，确认是否返回 JSON：
-
Springdoc:
http://localhost:8080/v3/api-docs -
Springfox:
http://localhost:8080/v2/api-docs
若返回 JSON，则 Swagger 已生效，问题在 UI 路径；若未返回，检查依赖和配置。
9. 其他可能原因
-
端口冲突：其他程序占用了
8080端口（通过netstat -ano | findstr :8080检查并终止进程）。 -
防火墙限制：确保防火墙允许
8080端口的本地访问。 -
项目未编译：代码修改后未重新编译，导致 Swagger 未生成。
快速测试步骤
-
启动应用，观察日志是否显示 Swagger 初始化信息。
-
直接访问
http://localhost:8080/v3/api-docs（Springdoc）或http://localhost:8080/v2/api-docs（Springfox）。 -
若返回 JSON，尝试访问
http://localhost:8080/swagger-ui/index.html。
通过以上排查，通常可解决 Swagger 无法访问的问题。
