非Spring Boot项目中无法使用springdoc-openapi-starter-webmvc-ui

1. 核对访问URL与Servlet上下文路径 #

如果你的应用配置了自定义Servlet上下文路径（比如部署在/myapp下），访问路径需改为http://localhost:<port>/myapp/swagger-ui.html，而非直接使用根路径。

2. 手动注册Swagger UI资源映射 #

Spring Boot会自动配置静态资源映射，但纯Spring MVC环境需要手动添加资源处理器。在你的@Configuration配置类中实现WebMvcConfigurer接口并添加映射规则：

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射Swagger UI的静态资源文件
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-starter-webmvc-ui/");
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-starter-webmvc-ui/");
    }
}

注意：不同版本的springdoc-openapi-starter-webmvc-ui可能资源路径略有差异，可打开jar包确认META-INF/resources/webjars/下的对应路径是否存在。

3. 手动定义OpenAPI Bean #

纯Spring环境不会自动生成OpenAPI元数据，必须手动配置Bean：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("你的API文档标题")
                        .version("1.0")
                        .description("API功能描述"));
    }
}

4. 确认组件扫描范围 #

确保你的配置类（WebConfig、OpenApiConfig）和REST控制器都在Spring的组件扫描范围内。如果是XML配置，需手动注册这些Bean；如果是注解配置，@ComponentScan要覆盖对应的包路径。

5. 验证依赖兼容性 #

除springdoc-openapi-starter-webmvc-ui外，需确保引入springdoc-openapi-starter-webmvc-api（部分场景需单独引入），且Spring 6核心依赖（如spring-webmvc）与Springdoc版本兼容。

6. 尝试替代访问端点 #

如果swagger-ui.html仍返回404，可尝试访问http://localhost:<port>/swagger-ui/index.html（部分版本的Springdoc使用该路径）。同时先访问http://localhost:<port>/v3/api-docs，若能返回JSON格式的API元数据，说明文档生成逻辑正常，问题仅出在Swagger UI的资源映射。

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