Spring MVC（非Spring Boot）集成SpringDoc后Swagger UI加载Petstore而非自定义API的问题求助

嘿，我之前在非SpringBoot的Spring MVC项目里集成SpringDoc时也踩过这个坑，太懂这种看到Petstore默认页面的无语感了！给你几个亲测有效的排查和解决方向，应该能帮你把自己的控制器API加载出来：

核心问题：SpringDoc在非SpringBoot环境下不会自动扫描控制器 #

SpringBoot里SpringDoc会自动做很多配置，但纯Spring MVC环境下得手动指定要扫描的API范围，不然它找不到你的控制器，就只能显示默认的Petstore。

1. 手动添加API分组扫描配置 #

在你的OpenApiConfig里新增一个GroupedOpenApi的Bean，明确指定要扫描的控制器包路径，这是最关键的一步：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("API Documentation").version("1.0")
                        .description("API running under /integration context path"));
    }

    // 新增这个Bean，指定你的控制器所在包
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("integration-apis") // 自定义分组名称
                .packagesToScan("com.yourproject.controllers") // 替换成你实际的控制器包路径
                .pathsToMatch("/integration/**") // 可选，过滤你的API路径前缀
                .build();
    }
}

2. 修正Swagger UI的配置，指向自己的API文档 #

默认情况下Swagger UI会指向Petstore的地址，你需要手动配置它指向你的v3/api-docs接口：
在配置类里新增SwaggerUiConfigParameters的Bean：

@Bean
public SwaggerUiConfigParameters swaggerUiConfigParameters() {
    SwaggerUiConfigParameters config = new SwaggerUiConfigParameters();
    config.setUrl("/integration/v3/api-docs"); // 注意要带上你的context path /integration
    config.setDeepLinking(true); // 可选，开启深度链接，方便直接跳转到具体API
    return config;
}

另外，你的WebConfig里的资源映射可以补充一个swagger-ui.html的直接映射，避免部分版本的路径匹配问题：

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/4.18.2/");
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/v3/api-docs/");
        // 新增swagger-ui.html的直接映射
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/4.18.2/index.html");
    }
}

3. 确保Spring能扫描到你的控制器 #

检查你的Spring配置，确保控制器所在的包被Spring的组件扫描覆盖到：

• 如果用注解配置，在你的核心配置类上加上@ComponentScan(basePackages = "com.yourproject")（替换成你项目的根包）
• 如果用XML配置，确保<context:component-scan base-package="com.yourproject.controllers" />已经配置
  毕竟如果Spring都没把你的控制器注册为Bean，SpringDoc根本找不到它们。

4. 先验证API文档接口是否正常 #

在调整配置后，先直接访问你的API文档地址：http://你的域名:端口/integration/v3/api-docs

• 如果返回的是你自己的API JSON文档，那说明SpringDoc已经正确生成了API，只是Swagger UI的配置问题
• 如果还是返回Petstore的内容，那回到第一步，检查GroupedOpenApi的包扫描路径是否正确，或者有没有拼写错误

5. 确认依赖版本一致性 #

检查你的依赖配置（Maven/Gradle），确保springdoc-openapi-ui和swagger-ui-webjar的版本和你配置里的一致，比如你用了4.18.2的swagger-ui，就要保证依赖里的版本也是4.18.2，避免资源加载不匹配的问题。

按照这些步骤一步步来，应该就能把Swagger UI切换到显示你自己的API了！

内容来源于stack exchange