SpringBoot 中 Swagger UI 无法显示 API 文档？终极解决指南

SpringBoot 中 Swagger UI 显示“No API definition provided.”：终极解决方案

问题

在 SpringBoot 应用程序中使用 Swagger UI 呈现 API 文档时，遇到了“No API definition provided.”错误。

深入分析：

根源：

此错误通常表明 Swagger UI 无法从应用程序获取有效的 OpenAPI 文档。这意味着 SpringBoot 应用程序可能没有正确配置或扫描到 API 端点。

解决步骤：

1. 依赖项检查：

• 确认使用的是最新版本的 SpringDoc 依赖项，例如 springdoc-openapi-starter-webmvc-ui。
• 确保已正确配置依赖项，包括指定包扫描路径。

2. 配置文件验证：

• 检查 application.properties 文件中以下配置的正确性：
  • springdoc.api-docs.path：API 文档路径
  • springdoc.swagger-ui.path：Swagger UI 路径
  • springdoc.packages-to-scan：要扫描的包路径

3. 控制器注解：

• 确认控制器类使用了必要的 OpenAPI 相关注解，如 @Operation 和 @ApiResponses。
• 确保注解信息正确反映了 API 方法。

4. 路径映射：

• 验证控制器中路径映射的正确性。
• 确认 Swagger UI 路径 (/v3/doc/swagger/swagger-ui.html) 可被访问。

5. 缓存清除：

• 尝试清除 IDE 缓存和重新构建项目。
• 考虑重启服务器或应用程序容器。

6. 版本说明：

• 确保 OpenAPI 文档指定了有效的版本字段，例如 openapi: 3.0.0。

7. 响应有效性：

• 检查应用程序是否在 /v3/doc/api-docs 路径上提供有效的 JSON 响应。
• 验证响应符合 OpenAPI 规范。

8. CSRF 配置：

• 确保 CSRF 配置正确。
• 在开发环境中，可以设置 springdoc.swagger-ui.csrf.enabled=false 以禁用 CSRF 保护。

其他技巧：

• 尝试使用不同的浏览器或清除浏览器缓存。
• 检查应用程序日志以查找有关此问题的错误或警告消息。
• 更新到 SpringBoot 和 SpringDoc 的最新版本。

结论：

解决 SpringBoot 中 Swagger UI 无法显示 API 文档的问题需要仔细检查配置、注解、路径映射和响应有效性。通过遵循本指南中的步骤，可以成功解决错误并获得可用的 API 文档。

常见问题解答：

1. 为什么 Swagger UI 显示“No API definition provided.”？

   • SpringBoot 应用程序可能没有正确配置或扫描到 API 端点。

2. 如何检查 OpenAPI 文档的版本字段？

   • 查看 /v3/doc/api-docs 路径上的 JSON 响应。版本字段通常位于文档的顶部。

3. CSRF 配置对 Swagger UI 有什么影响？

   • CSRF 保护可能会阻止 Swagger UI 访问 API 文档。在开发环境中，可以禁用 CSRF 保护。

4. 如何清除 IDE 缓存？

   • 方法因 IDE 而异。请参阅特定 IDE 的文档了解如何清除缓存。

5. 是否可以向 SpringBoot 应用程序添加自定义 OpenAPI 文档？

   • 可以使用 springdoc-openapi-webmvc-core 模块在应用程序中注册自定义 OpenAPI 文档。