Spring 5.2.0.RELEASE兼容Springdoc版本及Swagger文档访问排查

适配的Springdoc版本 #

Spring 5.2.0.RELEASE与springdoc-openapi-ui 1.7.0不兼容——1.7.0要求Spring Framework版本至少为5.3.0。你需要降级到springdoc-openapi-ui 1.6.14，这是适配Spring 5.2.x系列的最新稳定版本。

解决文档访问问题的步骤 #

1. 修正依赖配置 #

确保pom.xml（Maven）或build.gradle（Gradle）中使用正确的版本：

• Maven依赖：

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

• Gradle依赖：

  implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'
  

2. 检查OpenAPI配置类有效性 #

确认OpenApiConfiguration正确注册OpenAPI bean，且被Spring容器扫描到：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfiguration {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("项目API文档")
                        .version("1.0")
                        .description("API功能说明"));
    }
}

• 配置类需放在启动类所在包或其子包下，或通过@ComponentScan指定扫描路径。

3. 调整AppInitializer配置 #

如果你使用传统Spring MVC的AppInitializer，需添加Swagger相关配置类到Servlet配置中：

import org.springdoc.webmvc.ui.SwaggerConfig;
import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;

public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {
    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class[]{OpenApiConfiguration.class};
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class[]{SwaggerConfig.class};
    }

    @Override
    protected String[] getServletMappings() {
        return new String[]{"/"};
    }
}

• 注意：如果DispatcherServlet映射路径为/api/*，则API文档访问路径需调整为http://localhost:8081/api/v3/api-docs。

4. 配置Spring MVC资源处理器 #

添加资源映射，确保Spring能访问Swagger UI和API文档的静态资源：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

5. 验证访问路径 #

• 1.6.x版本默认API文档路径为/v3/api-docs，结合项目上下文路径访问：
  • 无上下文路径：http://localhost:8081/v3/api-docs
  • 上下文路径为/api：http://localhost:8081/api/v3/api-docs
• 可通过访问/swagger-ui/index.html验证文档是否生成成功。

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