Spring集成Swagger遇依赖问题：Bean创建失败与Base URL无法推断

问题重现 #

• 保留@Configuration与@EnableSwagger2注解时，启动抛出依赖错误：

  Error: "Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'apiListingScanner' defined in URL jar:file:/C:/Users////"

• 移除@Configuration后启动无报错，但访问Swagger UI时提示基础URL无法推断：

  Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually

当前项目的build.gradle依赖配置：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
    runtimeOnly'com.mysql:mysql-connector-j'
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

尝试Swagger 2.9.2和3.0.0版本均未解决问题。

解决方案 #

1. 优先切换到SpringDoc OpenAPI（推荐） #

Springfox（原Swagger官方维护库）已停止更新，与新版Spring Boot（2.6+）兼容性差。推荐使用Spring官方维护的SpringDoc OpenAPI，适配性更强：

步骤：

• 删除原有的springfox-swagger2和springfox-swagger-ui依赖
• 添加SpringDoc依赖到build.gradle：

  dependencies {
      // 移除旧Swagger依赖
      // implementation 'io.springfox:springfox-swagger2:2.9.2'
      // implementation 'io.springfox:springfox-swagger-ui:2.9.2'
      
      // 添加SpringDoc依赖
      implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
  }
  

• 删除自定义的SwaggerConfig.java，SpringDoc会自动扫描所有控制器，无需额外配置
• 访问Swagger UI：http://localhost:8080/swagger-ui.html（或/swagger-ui/index.html，依版本而定）

2. 若坚持使用Springfox的兼容配置 #

如果必须保留Springfox，需解决版本兼容和循环引用问题：

步骤：

1. 允许循环引用：在application.properties中添加配置，解决Spring Boot 2.6+禁用循环引用导致的Bean创建失败：

   spring.main.allow-circular-references=true
   

2. 修正Swagger配置类：确保包扫描和路径匹配正确，避免扫描范围错误：

   package com.platzi.market.web.config;
   
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   @Configuration
   @EnableSwagger2
   public class SwaggerConfig {
   
       @Bean
       public Docket api() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.platzi.market.web.controller"))
                   .paths(PathSelectors.any()) // 确保匹配所有API路径
                   .build();
       }
   }
   

3. 检查依赖冲突：运行./gradlew dependencies查看依赖树，排除与Spring Boot冲突的依赖（比如旧版本的Spring MVC相关依赖）

3. 关于Base URL推断问题 #

移除@Configuration会导致Swagger配置无法被Spring容器加载，这是错误操作，必须保留该注解才能让Swagger正常注册Bean和识别API路径，因此不要通过移除注解来规避启动错误。

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