Swagger 2.9.2 访问指南与常见问题排查

个人名片

🎓作者简介：java领域优质创作者
🌐个人主页：码农阿豪
📞工作室：新空间代码工作室（提供各种软件服务）
💌个人邮箱：[2435024119@qq.com]
📱个人微信：15279484656
🌐个人导航网站：www.forff.top
💡座右铭：总有人要赢。为什么不能是我呢？

• 专栏导航：

码农阿豪系列专栏导航
面试专栏：收集了java相关高频面试题，面试实战总结🍻🎉🖥️
Spring5系列专栏：整理了Spring5重要知识点与实战演练，有案例可直接使用🚀🔧💻
Redis专栏：Redis从零到一学习分享，经验总结，案例实战💐📝💡
全栈系列专栏：海纳百川有容乃大，可能你想要的东西里面都有🤸🌱🚀

目录

• 《Swagger 2.9.2 访问指南与常见问题排查》
• • 1. 引言
  • 2. Swagger 2.9.2 默认访问地址
  • • 2.1 基本访问路径
    • 2.2 不同 UI 版本的访问路径
    • 2.3 自定义 Context Path 的影响
  • 3. 如何正确配置 Swagger 2.9.2
  • • 3.1 添加 Maven 依赖
    • 3.2 启用 Swagger 配置类
    • 3.3 验证 Swagger 是否生效
  • 4. 常见问题与解决方案
  • • 4.1 访问 `swagger-ui.html` 返回 404
    • 4.2 Swagger 页面空白或加载失败
    • 4.3 如何自定义 Swagger 文档信息？
  • 5. 进阶：Swagger 增强工具（Knife4j）
  • • 5.1 添加 Knife4j 依赖
    • 5.2 访问 Knife4j UI
  • 6. 总结

《Swagger 2.9.2 访问指南与常见问题排查》

1. 引言

在现代 Java Web 开发中，Swagger 作为一款流行的 API 文档工具，极大地方便了前后端协作。然而，许多开发者在初次使用 Swagger 2.9.2 时，可能会遇到访问路径不正确、页面无法加载等问题。本文将详细介绍 Swagger 2.9.2 的默认访问地址、配置方式、常见问题及解决方案，并结合代码示例，帮助开发者快速上手。

---

2. Swagger 2.9.2 默认访问地址

2.1 基本访问路径

在 Spring Boot + Swagger 2.9.2 项目中，默认的 Swagger UI 访问地址是：

http://localhost:8080/swagger-ui.html

（假设服务运行在 8080 端口，若端口不同，需替换为实际端口。）

2.2 不同 UI 版本的访问路径

UI 类型	访问路径	适用场景
默认 Swagger UI	http://{host}:{port}/swagger-ui.html	标准 Swagger 界面
Knife4j（增强版）	http://{host}:{port}/doc.html	更友好的 UI，支持离线文档
Swagger Bootstrap UI	http://{host}:{port}/swagger-ui/index.html	旧版 UI，较少使用

2.3 自定义 Context Path 的影响

如果项目配置了 server.servlet.context-path（如 /api），则 Swagger 访问路径会变为：

http://localhost:8080/api/swagger-ui.html

示例配置（application.yml）：

server:
  servlet:
    context-path: /api

---

3. 如何正确配置 Swagger 2.9.2

3.1 添加 Maven 依赖

确保 pom.xml 包含以下依赖：

<!-- Swagger 核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- Swagger UI 依赖（提供可视化界面） -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.2 启用 Swagger 配置类

创建一个 SwaggerConfig 类，并添加 @EnableSwagger2 注解：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描的包
                .paths(PathSelectors.any())
                .build();
    }
}

3.3 验证 Swagger 是否生效

启动应用后，访问：

http://localhost:8080/v2/api-docs

如果返回 JSON 格式的 API 数据，说明 Swagger 配置成功。

---

4. 常见问题与解决方案

4.1 访问 swagger-ui.html 返回 404

可能原因：

1. 缺少 springfox-swagger-ui 依赖。
2. Spring Security 拦截了 Swagger 相关路径。
3. 项目未正确扫描 Controller 包。

解决方案：

• 检查依赖：确保 pom.xml 包含 springfox-swagger-ui。
• 配置 Spring Security 放行 Swagger（示例）：

  @Override
  public void configure(WebSecurity web) throws Exception {
      web.ignoring().antMatchers(
          "/swagger-ui.html",
          "/v2/api-docs",
          "/swagger-resources/",
          "/webjars/"
      );
  }
  

• 检查 @EnableSwagger2 和 Docket 配置，确保 basePackage 正确。

4.2 Swagger 页面空白或加载失败

可能原因：

1. 浏览器缓存问题。
2. 静态资源未正确加载（如 CSS/JS 404）。

解决方案：

• 强制刷新页面（Ctrl + F5）。
• 检查浏览器控制台，查看是否有资源加载失败。
• 手动访问 Swagger 资源路径，如：

  http://localhost:8080/webjars/springfox-swagger-ui/swagger-ui.css
  

  如果返回 404，可能是 Spring Boot 静态资源路径问题。

4.3 如何自定义 Swagger 文档信息？

在 Docket 配置中添加 apiInfo：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("API 文档")
            .description("Spring Boot + Swagger 示例")
            .version("1.0")
            .contact(new Contact("作者", "https://example.com", "contact@example.com"))
            .build();
}

---

5. 进阶：Swagger 增强工具（Knife4j）

如果默认 Swagger UI 不够友好，可以改用 Knife4j（基于 Swagger 的增强版）：

5.1 添加 Knife4j 依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

5.2 访问 Knife4j UI

http://localhost:8080/doc.html

Knife4j 提供更美观的界面，并支持离线文档导出。

---

6. 总结

本文详细介绍了 Swagger 2.9.2 的访问方式、配置方法及常见问题排查，主要内容包括：

1. 默认访问路径：http://localhost:8080/swagger-ui.html。
2. 正确配置 Swagger：依赖 + @EnableSwagger2 + Docket。
3. 常见问题：404、空白页面、Spring Security 拦截等。
4. 进阶方案：使用 Knife4j 增强 Swagger UI。

希望本文能帮助你顺利集成 Swagger，提升 API 开发效率！