SpringBoot3.1.5中OpenAPI接口文档正常但Swagger UI无数据

我基于SpringBoot3.1.5搭建了集成OpenAPI的项目，已通过@Operation等注解完成接口文档编写。访问配置的springdoc.api-docs.path路径可获取正确的接口文档JSON数据，但访问springdoc.swagger-ui.path路径时，Swagger UI仅显示“No API definition provided”，点击“explore”提示“提供的定义未指定有效版本字段”。我已尝试更换依赖版本、调整配置、执行mvn clean重建、清理IDE缓存等操作，且相同配置在其他项目中可正常运行，现寻求解决办法。

依赖配置 #

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

application.properties配置 #

springdoc.api-docs.path                         =/v3/doc/api-docs
springdoc.api-docs.enabled                      =true
springdoc.swagger-ui.csrf.enabled               =false
springdoc.swagger-ui.with-credentials           =false
springdoc.swagger-ui.filter                     =false
springdoc.swagger-ui.syntax-highlight.activated =true
springdoc.swagger-ui.enabled                    =true
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.path                       =/v3/doc/swagger/swagger-ui.html
springdoc.packages-to-scan                      =de.my.rootPackage

控制器代码 #

@RestController
@RequestMapping("/root")
@Validated
public class MyController{
    
    private MyService myService;

    public MyController(final MyService  myService) {
        this.myService= myService;
    }
    
    @Operation(summary = "保存数据", description = "该接口用于保存新数据。")
    @Parameter(content = @Content(schema = @Schema(implementation = DataDto.class), mediaType = "application/json"))
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "自定义描述", content = @Content),
            @ApiResponse(responseCode = "201", description = "自定义描述", content = @Content),
            @ApiResponse(responseCode = "400", description = "收到无效请求。", content = @Content),
            @ApiResponse(responseCode = "500", description = "发生内部错误。", content = @Content),
    })
    @PostMapping(value = "/save", consumes = TYPE_JSON)
    public ResponseEntity saveClinic(@NotNull @Valid @RequestBody final DataDto dataDto){
        // 业务代码
    }
}

解决办法 #

1. 显式指定Swagger UI的API文档路径 #

你禁用了Swagger默认URL，但未手动指定自定义的API文档地址，导致UI无法找到数据源。在application.properties中添加：

springdoc.swagger-ui.url=/v3/doc/api-docs

2. 配置OpenAPI版本信息 #

添加配置类显式定义OpenAPI的版本元数据，解决“未指定有效版本字段”的问题：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("项目API文档")
                        .version("1.0.0")
                        .description("接口功能描述"));
    }
}

3. 验证包扫描路径正确性 #

确认de.my.rootPackage确实包含你的控制器类，可临时注释springdoc.packages-to-scan配置，让springdoc自动扫描所有包，排查路径拼写错误问题。

4. 清理浏览器缓存 #

浏览器可能缓存了旧的Swagger UI资源，使用Ctrl+Shift+R强制刷新页面，或通过无痕模式访问验证。

5. 测试依赖版本兼容性 #

尝试将springdoc依赖降级到2.2.0（SpringBoot3.1.5兼容版本），排除版本适配的隐性问题：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

内容的提问来源于stack exchange，提问作者JAlways