基于WebMvcConfigurationSupport的老项目集成SpringDoc Swagger UI失败求助

问题根源 #

使用WebMvcConfigurationSupport会屏蔽Spring Boot的部分自动配置，包括SpringDoc用于替换默认Petstore页面的SwaggerIndexPageTransformer无法自动注册，同时Swagger的核心配置也未被正确加载，导致只能显示默认UI。

具体解决方案 #

1. 确认依赖（若未正确引入）

确保pom.xml（或build.gradle）中引入SpringDoc WebMvc Starter依赖：

<!-- Maven -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 可根据项目需求选择对应版本 -->
</dependency>

2. 在WebMvc配置类中手动注册转换器与资源

在你的WebMvcConfigurationSupport子类中，注入必要的SpringDoc组件，并手动添加资源转换器：

import org.springdoc.webmvc.ui.SwaggerIndexPageTransformer;
import org.springdoc.core.properties.SwaggerUiConfigProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class CustomWebMvcConfig extends WebMvcConfigurationSupport {

    @Autowired
    private SwaggerIndexPageTransformer swaggerIndexPageTransformer;

    @Autowired
    private SwaggerUiConfigProperties swaggerUiConfigProperties;

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 配置Swagger UI资源路径，引入版本属性避免硬编码
        registry.addResourceHandler(swaggerUiConfigProperties.getPath() + "/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/" + swaggerUiConfigProperties.getVersion() + "/")
                .resourceChain(false)
                // 关键：添加SwaggerIndexPageTransformer，替换默认Petstore页面
                .addTransformer(swaggerIndexPageTransformer);

        // 确保API文档端点可访问
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/");

        // 保留原有项目的静态资源配置
        super.addResourceHandlers(registry);
    }
}

3. 配置OpenAPI文档（必要步骤）

手动创建OpenAPI配置类，确保Swagger能扫描到项目接口：

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")
                        .description("项目接口的Swagger文档"));
    }
}

4. 排除拦截器/过滤器对Swagger路径的拦截

如果项目有登录拦截器或全局过滤器，需放行以下路径：

• /swagger-ui/**
• /v3/api-docs/**
• /swagger-resources/**

示例拦截器配置：

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(loginInterceptor)
            .addPathPatterns("/**")
            .excludePathPatterns("/swagger-ui/**", "/v3/api-docs/**", "/swagger-resources/**");
    super.addInterceptors(registry);
}

5. 验证效果

启动项目后访问http://localhost:端口/swagger-ui/index.html，此时应该加载你项目的接口文档，而非默认Petstore页面。

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