SpringDoc OpenAPI与Spring Webflux集成中Swagger UI无法访问的解决方案

在使用SpringDoc OpenAPI与Spring Webflux集成时，开发人员可能会遇到一个常见问题：虽然API文档端点（/v3/api-docs）能够正常工作，但Swagger UI界面（/swagger-ui.html）却返回404错误。这种情况通常是由于依赖配置不完整导致的。

问题现象

当开发人员按照常规方式配置SpringDoc OpenAPI时，可能会观察到以下现象：

1. API文档端点能够正常响应
2. Swagger UI界面无法访问
3. 控制台没有明显的错误日志

根本原因

这个问题的主要原因是缺少必要的UI依赖模块。在Spring Webflux环境中，仅仅引入核心API模块是不够的，还需要专门引入Webflux UI模块才能正常显示Swagger界面。

解决方案

要解决这个问题，需要在项目的构建配置文件中添加以下依赖：

implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.6.0")

这个依赖提供了Spring Webflux环境下Swagger UI所需的所有组件和资源。

完整依赖配置

对于完整的Spring Webflux项目，建议同时包含以下依赖：

/* spring doc OpenAPI */
implementation("org.springdoc:springdoc-openapi-starter-webflux-api:2.6.0")
implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.6.0")
implementation("org.springdoc:springdoc-openapi-starter-common:2.6.0")

配置建议

除了依赖配置外，还可以考虑以下配置优化：

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    operations-sorter: method
  default-produces-media-type: application/json

验证步骤

配置完成后，可以通过以下步骤验证是否正常工作：

1. 启动应用程序
2. 访问/v3/api-docs端点，确认API文档能够正常返回
3. 访问/swagger-ui.html，应该能看到Swagger UI界面

总结

SpringDoc OpenAPI为Spring Webflux应用提供了强大的API文档支持，但在集成过程中需要注意完整引入所有必要的模块。特别是Webflux环境下的UI模块，与传统的Spring MVC环境有所不同。通过正确配置依赖，可以轻松解决Swagger UI无法访问的问题，为API开发提供便利的文档和测试界面。