SpringBoot集成Swagger后，接口文档无法正常显示的问题如何解决？

Question

在SpringBoot项目中集成Swagger后，接口文档无法正常显示，常见原因是依赖版本不匹配或配置错误。首先，确保引入的Swagger依赖与SpringBoot版本兼容，例如使用`springfox-boot-starter`作为依赖时，需注意其版本要求。其次，检查是否正确添加了Swagger配置类，通常需要通过`@EnableSwagger2`注解启用，并正确设置`Docket` Bean，如指定包扫描路径。如果项目启用了安全配置（如Spring Security），可能拦截了Swagger的默认路径，需在安全配置中放行相关URL（如`/swagger-ui.html`和`/v2/api-docs`）。此外，SpringBoot 3及以上版本建议使用`springdoc-openapi`替代Springfox，以避免兼容性问题。最后，确认应用运行时访问的URL为`http://localhost:/swagger-ui.html`，若仍不可见，可查看控制台或日志排查具体异常原因。

Answer 1

1. 问题概述

在SpringBoot项目中集成Swagger后，接口文档无法正常显示的问题非常常见。这通常涉及依赖版本不匹配、配置错误或安全策略冲突等原因。以下将从浅入深地分析问题的可能原因及解决方案。

• 依赖版本不兼容
• Swagger配置类缺失或错误
• Spring Security拦截默认路径
• SpringBoot 3及以上版本的特殊要求

2. 常见问题与排查方法

以下是针对不同场景下的常见问题及解决思路：

问题描述	可能原因	解决方案
Swagger界面无法加载	依赖版本不匹配	确保`springfox-boot-starter`版本与SpringBoot版本兼容（例如SpringBoot 2.x使用Springfox 3.x）。
访问Swagger页面时404	未正确配置Swagger Bean	检查是否添加了`@EnableSwagger2`注解，并正确配置`Docket` Bean。
Spring Security拦截Swagger路径	安全配置未放行Swagger相关URL	在Spring Security配置中放行`/swagger-ui.html`和`/v2/api-docs`等路径。

3. 配置示例

以下是Swagger配置类的代码示例：

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    }
    

如果使用SpringBoot 3及以上版本，建议替换为`springdoc-openapi`：

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
        <version>2.1.0</version>
    </dependency>
    

4. 安全配置调整

若项目启用了Spring Security，需在安全配置中明确放行Swagger相关路径：

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

5. 排查流程

以下是问题排查的推荐流程图：

graph TD;
            A[接口文档不可见] --> B{依赖版本匹配？};
            B --否--> C[检查依赖版本];
            B --是--> D{配置类正确？};
            D --否--> E[修复配置类];
            D --是--> F{Spring Security启用？};
            F --否--> G[检查URL路径];
            F --是--> H[放行Swagger路径];