Springdoc v2.5.0如何加载Gradle依赖库中Openapi.yml配置？

方法1：通过OpenApiCustomizer加载外部YAML #

你可以实现OpenApiCustomizer接口，读取依赖库中的openapi.yml并合并到Springdoc的OpenAPI实例里：

import io.swagger.v3.core.util.Yaml;
import io.swagger.v3.oas.models.OpenAPI;
import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;
import java.io.InputStream;

@Configuration
public class ExternalOpenApiConfig {

    @Bean
    public OpenApiCustomizer externalOpenApiCustomizer() {
        return openApi -> {
            try (InputStream inputStream = new ClassPathResource("openapi.yml").getInputStream()) {
                OpenAPI externalOpenApi = Yaml.mapper().readValue(inputStream, OpenAPI.class);
                // 按需合并外部OpenAPI内容到现有实例，可调整合并逻辑
                openApi.paths(externalOpenApi.getPaths());
                openApi.components(externalOpenApi.getComponents());
                openApi.info(externalOpenApi.getInfo());
            } catch (IOException e) {
                throw new RuntimeException("加载外部OpenAPI YAML失败", e);
            }
        };
    }
}

这个方法会把依赖库的API描述合并到Springdoc自动生成的（如果有）OpenAPI实例中，Swagger-UI会自动展示合并后的内容。

方法2：直接配置Swagger-UI指向依赖库资源 #

如果你的网关不需要自动生成接口文档，只想展示依赖库的openapi.yml，可以在application.yml里配置Springdoc的Swagger-UI参数：

springdoc:
  swagger-ui:
    urls:
      - url: classpath:/openapi.yml
        name: 外部API文档

要是直接配置不生效，先检查ClassPathResource("openapi.yml")能不能读取到文件——比如在配置类里打印new ClassPathResource("openapi.yml").exists()的结果。如果读不到，检查Gradle依赖配置，确保依赖库的resources被正确打包并引入到项目类路径中。

方法3：手动注册OpenAPI实例 #

直接读取依赖库的YAML文件，构建完整的OpenAPI实例并注册为Bean，Springdoc会自动识别这个实例并在Swagger-UI展示：

import io.swagger.v3.core.util.Yaml;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;

import java.io.IOException;
import java.io.InputStream;

@Configuration
public class ExternalOpenApiConfig {

    @Bean
    public OpenAPI externalOpenAPI() throws IOException {
        try (InputStream inputStream = new ClassPathResource("openapi.yml").getInputStream()) {
            return Yaml.mapper().readValue(inputStream, OpenAPI.class);
        }
    }
}

这种方式会完全替换Springdoc自动生成的OpenAPI实例，只展示依赖库的API文档。

额外排查点 #

• 确认依赖库的openapi.yml确实在src/main/resources目录下，并且Gradle打包时包含了该文件（可以解压依赖库的jar包，检查根目录是否有这个文件）。
• 如果依赖库是多模块项目，确保该模块的resources配置正确，没有被Gradle忽略。
• 若使用Spring Cloud Gateway，检查是否有路由规则拦截了Swagger-UI的请求，确保/swagger-ui/**和/v3/api-docs/**路径能正常访问。

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