Spring租车应用Swagger无法正常工作，请求排查原因

针对你遇到的Swagger无法正常工作的问题，结合Spring Boot集成Swagger的常见坑，给你整理几个排查方向：

• 检查Swagger依赖是否匹配Spring Boot版本
  注意Spring Boot 3+不再兼容springfox，必须用SpringDoc作为替代：

  • Spring Boot 2.x用springfox：

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    

  • Spring Boot 3+用SpringDoc：

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.2.0</version>
    </dependency>
    

• 验证Swagger配置类/配置项正确性

  • springfox需要配置Docket Bean并开启@EnableSwagger2：

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket api() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.your.rental.controller")) // 替换为你的Controller包路径
                    .paths(PathSelectors.any())
                    .build();
        }
    }
    

  • SpringDoc无需额外配置类，但可通过配置文件开启：

    springdoc.api-docs.enabled=true
    springdoc.swagger-ui.enabled=true
    

• 确认访问路径是否正确

  • springfox默认访问地址：http://localhost:端口/swagger-ui.html
  • SpringDoc默认访问地址：http://localhost:端口/swagger-ui/index.html
  • 如果应用有上下文路径，需加上前缀，比如http://localhost:端口/your-context/swagger-ui.html

• 检查拦截器/过滤器是否拦截Swagger请求
  如果用了Spring Security或自定义拦截器，必须放行Swagger相关路径：

  // Spring Security示例（springfox）
  @Override
  protected void configure(HttpSecurity http) throws Exception {
      http.authorizeRequests()
              .antMatchers("/swagger-ui/**", "/v2/api-docs", "/swagger-resources/**", "/webjars/**")
              .permitAll()
              .anyRequest().authenticated();
  }
  

• 查看启动日志中的Swagger相关报错
  搜索日志里的swagger、springfox或springdoc关键词，看是否有类扫描失败、依赖冲突、反射异常等信息，这是定位问题最直接的方式。

• 检查Controller注解是否规范
  确保Controller类标注了@RestController/@Controller，方法标注了@GetMapping/@PostMapping等请求注解，Swagger依赖这些注解生成接口文档。

如果以上排查都没解决问题，建议补充以下信息：

• Spring Boot具体版本
• Swagger依赖的完整配置
• 应用启动日志的报错片段
• 访问Swagger页面时的浏览器控制台错误

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