返回

Springboot整合Swagger 3.0.0 访问Swagger-ui.html 报404的解决方法

后端

解决 Swagger 3.0.0 集成中的 404 错误：终极指南

序言

Swagger 是一款颇受欢迎的开源工具，用于生成、记录和测试 RESTful API。它提供了一个用户友好的界面，使得 API 查看和互动式测试变得轻而易举。本文将重点讨论 Springfox，这是一个专为 Spring Boot 设计的 Swagger 工具包。我们将深入探讨如何解决 Springfox 集成 Swagger 3.0.0 时可能遇到的 404 错误，并提供分步指导以帮助您解决这一问题。

症状：令人头疼的 404 错误

当您尝试访问 Swagger-ui.html 以查看您的 API 文档时，却遇到了一个讨厌的 404 错误。这个错误表示您正在寻找的页面不存在或不可用。令人沮丧，对吧？

诊断：深入分析问题根源

要解决 404 错误，第一步是诊断问题根源。以下是一些可能导致该错误的原因：

  • 错误的 Springfox 依赖项： 确保您的 pom.xml 文件中添加了正确的 Springfox 依赖项。对于 Swagger 3.0.0，您需要包含以下依赖项：
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-bean-validators</artifactId>
    <version>3.0.0</version>
</dependency>
  • 缺失的 Swagger 配置： 在您的 Spring Boot 应用中，您需要使用 @EnableSwagger2 注解启用 Swagger。您还可以使用 basePackages 参数指定 API 文档的扫描路径：
@SpringBootApplication
@EnableSwagger2(basePackages = {"com.example.demo.controller"})
  • 错误的 URL 路径： 确保您在浏览器中输入的 URL 路径正确无误。对于 Swagger 3.0.0，您需要访问以下 URL：
http://localhost:8080/swagger-ui.html
  • 防火墙或代理问题： 检查您的防火墙或代理服务器设置，确保它们不会阻止对 Swagger-ui.html 的访问。

治疗：逐步修复 404 错误

一旦您确定了问题的根源，就可以采取以下步骤解决 404 错误：

  1. 验证 Swagger 依赖项： 仔细检查您的 pom.xml 文件，确保您已正确添加了 Springfox 依赖项。

  2. 配置 Swagger： 在您的 Spring Boot 应用中，添加 @EnableSwagger2 注解并指定 API 文档的扫描路径。

  3. 确认 URL 路径： 在浏览器中，输入正确的 URL 路径 http://localhost:8080/swagger-ui.html，确保端口号与您的应用匹配。

  4. 排除其他原因： 禁用您的防火墙或代理，并清除浏览器的缓存和 cookie。如果问题仍然存在，请检查您的应用是否已成功启动。

预防：规避 404 错误的秘诀

为了避免将来出现 404 错误，请遵循这些最佳实践：

  • 使用最新版本的 Springfox 依赖项，以确保您拥有最新功能和错误修复。
  • 仔细检查 Swagger 配置，确保 Swagger 已启用，并且 API 文档扫描路径已正确定义。
  • 在开发和测试环境中使用 Swagger，以便尽早发现和解决问题。
  • 定期更新 Swagger 文档，以使其与您的应用代码保持同步。

结论

解决 Springfox 集成 Swagger 3.0.0 时出现的 404 错误并不难，只要您遵循本文提供的步骤。通过正确配置 Swagger 依赖项、验证 Swagger 配置、确认 URL 路径并排除其他潜在原因，您就可以轻松解决此问题。

常见问题解答

  1. 为什么在访问 Swagger-ui.html 时会收到 404 错误？

    • 最常见的原因是错误的 Springfox 依赖项、缺失的 Swagger 配置、错误的 URL 路径或防火墙或代理问题。

  2. 如何解决 Springfox 中的 404 错误？

    • 首先验证 Swagger 依赖项，然后检查 Swagger 配置和 URL 路径。排除其他潜在原因，例如防火墙或代理问题。

  3. 如何防止将来出现 404 错误？

    • 使用最新版本的 Springfox 依赖项，仔细检查 Swagger 配置，并在开发和测试环境中使用 Swagger。定期更新 Swagger 文档，以使其与您的应用代码保持同步。

  4. 为什么在 Swagger 集成中使用 Springfox？

    • Springfox 是一个专门为 Spring Boot 设计的 Swagger 工具包，它使得在 Spring Boot 应用中集成 Swagger 变得简单快捷。

  5. Swagger-ui.html 位于哪里？

    • Swagger-ui.html 文件通常位于您的 Spring Boot 应用的 /public 目录中。