SpringBoot集成springdoc-openapi-ui访问swagger-ui.html出现404问题如何解决？

Question

在SpringBoot项目中集成springdoc-openapi-ui时，访问`swagger-ui.html`出现404问题，通常是由于依赖配置错误或路径映射不正确导致。首先，确保`pom.xml`中已正确添加`springdoc-openapi-ui`依赖，版本需与SpringBoot兼容。其次，检查是否启用MVC相关组件，如`@EnableWebMvc`可能导致路径冲突，建议移除该注解或调整配置。此外，springdoc默认访问路径为`/swagger-ui/index.html`而非`swagger-ui.html`，访问时应使用正确路径。若仍存在问题，可尝试设置`springdoc.api-docs.path`和`springdoc.swagger-ui.path`属性，自定义API文档和UI的访问路径。最后，确认项目中是否存在安全配置（如Spring Security），如有，需为Swagger相关路径放行访问权限。

Answer 1

1. 问题概述

在SpringBoot项目中集成springdoc-openapi-ui时，访问`swagger-ui.html`出现404问题，通常是由以下原因导致的：依赖配置错误、路径映射不正确、MVC组件冲突或安全配置限制。以下是逐步排查和解决问题的方法。

• 确保`pom.xml`中已正确添加`springdoc-openapi-ui`依赖。
• 确认依赖版本与SpringBoot兼容。
• 检查是否存在路径冲突或其他配置问题。

2. 依赖配置检查

首先，确保`pom.xml`文件中已正确引入`springdoc-openapi-ui`依赖。以下是正确的依赖配置示例：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

注意，版本号应根据实际使用的SpringBoot版本进行调整。例如，SpringBoot 2.x建议使用springdoc 1.x版本。

3. 路径映射与默认路径

springdoc默认提供的Swagger UI访问路径为`/swagger-ui/index.html`，而非传统的`swagger-ui.html`。如果直接访问`swagger-ui.html`会导致404错误。因此，请尝试通过以下路径访问：

路径	说明
/swagger-ui/index.html	默认的Swagger UI页面入口
/v3/api-docs	OpenAPI文档JSON接口

若需自定义路径，可通过以下属性配置：

springdoc.api-docs.path=/custom-api-docs
springdoc.swagger-ui.path=/custom-swagger-ui

4. MVC组件冲突分析

启用`@EnableWebMvc`注解可能会导致路径映射冲突，因为该注解会覆盖Spring Boot自动配置的默认行为。建议移除`@EnableWebMvc`注解，或者在保留该注解的情况下手动配置静态资源映射：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
               .addResourceLocations("classpath:/META-INF/resources/swagger-ui/");
    }
}

此方法可确保Swagger UI的静态资源能够正确加载。

5. 安全配置检查

如果项目中集成了Spring Security，可能需要为Swagger相关路径放行访问权限。以下是配置示例：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
            .anyRequest().authenticated();
    }
}

通过上述配置，可以确保Swagger UI和API文档能够正常访问。

6. 排查流程图

以下是解决404问题的排查流程图：

graph TD;
            A[访问swagger-ui.html失败] --> B{是否正确配置依赖?};
            B --否--> C[检查pom.xml];
            B --是--> D{路径是否正确?};
            D --否--> E[使用默认路径/swagger-ui/index.html];
            D --是--> F{是否启用@EnableWebMvc?};
            F --是--> G[调整静态资源映射];
            F --否--> H{是否启用Spring Security?};
            H --是--> I[为Swagger路径放行];