如何配置springdoc-openapi-ui使其不映射根路径？

针对你在非SpringBoot的Spring Web应用中遇到的这个映射冲突问题，我整理了几个亲测可行的解决思路：

方法一：通过WebMvc配置重指定Swagger UI访问路径 #

由于是非SpringBoot环境，自动配置逻辑可能没完全生效，springdoc.swagger-ui.use-root-path=false属性可能未被正确加载。你可以自定义WebMvcConfigurer来调整SwaggerUiHome的映射路径，同时保留自己的"/"控制器：

import org.springdoc.webmvc.ui.SwaggerUiHome;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SpringDocWebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addViewControllers(ControllerRegistry registry) {
        // 移除SwaggerUiHome默认的"/"映射
        registry.removeViewController("/");
        // 给SwaggerUiHome指定新的访问路径，比如"/swagger-ui-entry"
        registry.addViewController("/swagger-ui-entry")
                .setControllerBeanName("swaggerUiHome");
    }
}

配置完成后，Swagger UI首页会切换到/swagger-ui-entry，你的自定义"/"控制器就能正常运行了。

方法二：重写SwaggerUiHome Bean修改映射 #

如果上面的方法不生效，你可以直接重新定义SwaggerUiHome Bean，覆盖原有的请求映射：

import org.springdoc.webmvc.ui.SwaggerUiHome;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;

@Configuration
public class CustomSwaggerUiConfig {

    @Bean
    public SwaggerUiHome customSwaggerUiHome() {
        return new SwaggerUiHome() {
            // 把映射路径改为你需要的，比如"/swagger-home"
            @GetMapping("/swagger-home")
            public String index() {
                return super.index();
            }
        };
    }
}

这个方式直接替换了原SwaggerUiHome的index方法映射，从根源上避免了和"/"路径的冲突。

方法三：手动初始化springdoc配置属性 #

非SpringBoot环境下，需要手动加载springdoc的配置属性，确保use-root-path=false生效：

import org.springdoc.core.SpringDocConfigProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {

    @Bean
    public SpringDocConfigProperties springDocConfigProperties() {
        SpringDocConfigProperties properties = new SpringDocConfigProperties();
        // 关闭根路径映射
        properties.getSwaggerUi().setUseRootPath(false);
        // 可选：指定Swagger UI的基础访问路径
        properties.getSwaggerUi().setPath("/swagger-ui");
        return properties;
    }
}

同时要确保你已经正确配置了OpenAPI的基础Bean，比如：

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("My API")
                        .version("1.0")
                        .description("Documentation for my Spring Web API"));
    }
}

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