SpringBoot集成 SpringDoc (SpringFox 和 Swagger 的升级版)

阅读 SpringDoc 官网 - Migrating from SpringFox

只需要导入以下一个依赖即可：

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

配置 application.yaml 中配置 SpringDoc 相关信息, 参考 SpringDoc 官网 - swagger-ui-properties

我的配置如下：

springdoc:
  packages-to-scan:
    - com.tyler.web
  swagger-ui:
    doc-expansion: none
    url: "/v3/api-docs"
    path: /swagger-ui.html
  api-docs:
    enabled: true
    path: "/v3/api-docs"

然后创建 SpringDoc 的配置类

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Yxai API")
                        .description("Yxai Restfull API")
                        .version("v0.0.1")
                        .license(new License().name("Yxai 1.0")));
    }
}

然后启动 SpringBoot 项目，报错如下：

java.lang.IllegalStateException: Error processing condition on org.springdoc.webmvc.ui.SwaggerConfig.springWebProvider
at org.springframework.boot.autoconfigure.condition.SpringBootCondition.matches(SpringBootCondition.java:60) ~[spring-boot-autoconfigure-3.1.12.jar:3.1.12]
at org.springframework.context.annotation.ConditionEvaluator.shouldSkip(ConditionEvaluator.java:108) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.loadBeanDefinitionsForBeanMethod(ConfigurationClassBeanDefinitionReader.java:183) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.loadBeanDefinitionsForConfigurationClass(ConfigurationClassBeanDefinitionReader.java:144) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.annotation.ConfigurationClassBeanDefinitionReader.loadBeanDefinitions(ConfigurationClassBeanDefinitionReader.java:120) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.annotation.ConfigurationClassPostProcessor.processConfigBeanDefinitions(ConfigurationClassPostProcessor.java:427) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.annotation.ConfigurationClassPostProcessor.postProcessBeanDefinitionRegistry(ConfigurationClassPostProcessor.java:287) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanDefinitionRegistryPostProcessors(PostProcessorRegistrationDelegate.java:344) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.support.PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(PostProcessorRegistrationDelegate.java:115) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.support.AbstractApplicationContext.invokeBeanFactoryPostProcessors(AbstractApplicationContext.java:778) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:597) ~[spring-context-6.0.21.jar:6.0.21]
at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:146) ~[spring-boot-3.1.12.jar:3.1.12]
at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:739) ~[spring-boot-3.1.12.jar:3.1.12]
at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:441) ~[spring-boot-3.1.12.jar:3.1.12]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:325) ~[spring-boot-3.1.12.jar:3.1.12]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1327) ~[spring-boot-3.1.12.jar:3.1.12]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1316) ~[spring-boot-3.1.12.jar:3.1.12]
at com.yxai.web.WebApplication.main(WebApplication.java:15) ~[classes/:na]
Caused by: java.lang.IllegalStateException: Failed to introspect Class [org.springdoc.webmvc.ui.SwaggerConfig] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@63947c6b]
at org.springframework.util.ReflectionUtils.getDeclaredMethods(ReflectionUtils.java:483) ~[spring-core-6.0.21.jar:6.0.21]

这个错误的原因是我的 SpringBoot 版本和 SpirngDoc 版本不匹配问题。

我的SpringBoot 版本为 3.1.12， 而 SpirngDoc 的版本为 2.7.0 。

降级 SpringDoc 版本到 2.3.0 即可。

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

再次启动项目正常了。

然后访问 http://localhost:9090/swagger-ui/index.html 可以看到接口文档了。