Spring 6（非Spring Boot）中Swagger/SpringDoc配置问题求助

问题核心 #

API通过/CONTEXT-PATH/api暴露，swagger-ui可通过/CONTEXT-PATH/api/swagger-ui/index.html访问，但swagger-ui会请求不存在的/CONTEXT-PATH/v3/api-docs/swagger-config，且手动访问正确路径/CONTEXT-PATH/api/v3/api-docs/swagger-config时，返回的configUrl仍指向错误路径。

配置修正方案 #

1. 调整配置文件（application.properties） #

移除硬编码的CONTEXT-PATH，改用相对路径避免冲突：

# 禁用swagger默认URL
springdoc.swagger-ui.disable-swagger-default-url=true
# 配置swagger-config的相对路径（基于servlet path）
springdoc.swagger-ui.configUrl=/api/v3/api-docs/swagger-config
# api-docs的基础路径（相对于servlet path）
springdoc.api-docs.path=/v3/api-docs
# 非Spring Boot环境下，context path建议直接在容器（如Tomcat）中配置，无需在此设置
# spring.mvc.servlet.path=/api 保持原有配置即可

2. 修改Java配置类 #

显式配置SpringDoc的属性Bean，确保路径生效，并添加静态资源映射：

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = {
        "mypackage.rest",
        "org.springdoc"
})
@PropertySource("classpath:/application.properties")
@Import({
    SpringDocConfiguration.class,
    SpringDocWebMvcConfiguration.class,
    MultipleOpenApiSupportConfiguration.class,
    org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class
})
public class BoApiConfiguration implements WebMvcConfigurer {
    
    @Autowired
    private Environment environment;

    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }

    // 显式配置Swagger UI属性
    @Bean
    public SwaggerUiConfigProperties swaggerUiConfigProperties() {
        SwaggerUiConfigProperties properties = new SwaggerUiConfigProperties();
        properties.setDisableSwaggerDefaultUrl(true);
        properties.setConfigUrl("/api/v3/api-docs/swagger-config");
        return properties;
    }

    // 显式配置API Docs属性
    @Bean
    public ApiDocsProperties apiDocsProperties() {
        ApiDocsProperties properties = new ApiDocsProperties();
        properties.setPath("/v3/api-docs");
        return properties;
    }
    
    @Bean
    public GroupedOpenApi groupOpenAPI() {
         return GroupedOpenApi.builder()
            .group("api")
            .packagesToScan("eu.europa.ec.comm.euaroundme.web.rest")
            .addOpenApiCustomizer(serverOpenApiCustomizer())
            .build();
    }
    
    public OpenApiCustomizer serverOpenApiCustomizer() {
        String url = environment.getProperty(ApplicationConstants.APPLICATION_URL_PARAM_KEY);
        url += "/api";
        Server server = new Server().url(url).description("apiServer");
        List<Server> servers = new ArrayList<>();
        servers.add(server);
        return openApi -> openApi.setServers(servers);
    }

    // 手动映射Swagger UI静态资源（非Spring Boot环境必需）
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/");
    }
    
}

关键说明 #

• 非Spring Boot环境下，server.servlet.context-path属性可能不生效，建议直接在容器（如Tomcat）的部署配置中设置上下文路径。
• 通过Java配置类显式创建SwaggerUiConfigProperties和ApiDocsPropertiesBean，确保配置被Spring正确加载（非Spring Boot环境下自动属性绑定可能失效）。
• 添加静态资源映射，避免swagger-ui的前端文件出现404错误。

验证步骤 #

1. 启动应用后访问/CONTEXT-PATH/api/swagger-ui/index.html，查看浏览器网络请求，确认swagger-config的请求路径为/CONTEXT-PATH/api/v3/api-docs/swagger-config。
2. 访问/CONTEXT-PATH/api/v3/api-docs/swagger-config，检查返回内容中的configUrl是否指向正确路径。

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