当前位置：首页 > news >正文

swagger访问不了的解决方案 http://localhost:8080/swagger-ui/index.html

news 来源：原创 2025/6/28 9:14:41

确保增加 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 无法访问的问题。