Spring Boot项目如何复用旧swagger.yaml中的对象定义？

我开发的Spring Boot应用通过Swagger自动生成API文档，现在手里有一份包含大量对象定义的旧swagger.yaml文件，不想把这些定义重写成Java类，想直接访问该文件复用里面的已有定义，请问这个需求能实现吗？期望的用法示例如下：

@Schema(name = "name", description = "description", ref = swagger.yaml中的定义)
private SomeClass someClass;

当然可以实现，下面是基于主流的SpringDoc OpenAPI（替代旧Springfox方案）的具体实现步骤：

1. 引入依赖 #

确保项目中引入SpringDoc核心依赖：

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

2. 加载并合并外部swagger.yaml #

创建配置类，将外部swagger.yaml中的schema定义合并到自动生成的API文档：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() throws IOException {
        // 加载外部yaml文件，示例路径为src/main/resources下的old-swagger.yaml
        InputStream yamlStream = getClass().getResourceAsStream("/old-swagger.yaml");
        OpenAPIImporter importer = new OpenAPIImporter();
        OpenAPI externalOpenApi = importer.importYaml(yamlStream);

        // 初始化当前项目的API文档基础配置
        OpenAPI currentOpenApi = new OpenAPI()
                .info(new Info().title("业务API文档").version("1.0.0"));

        // 合并外部yaml中的schema定义到当前文档的components
        if (externalOpenApi.getComponents() != null && externalOpenApi.getComponents().getSchemas() != null) {
            currentOpenApi.components(new Components().schemas(externalOpenApi.getComponents().getSchemas()));
        }

        return currentOpenApi;
    }
}

3. 在代码中引用外部定义 #

直接通过@Schema的ref属性指定外部yaml中schema的路径，格式为#/components/schemas/[你的schema名称]，字段类型可使用Object（无需编写对应Java类）：

@Schema(name = "someClass", description = "业务对象描述", ref = "#/components/schemas/OldUserModel")
private Object someClass;

注意事项 #

• 若旧swagger.yaml是Swagger 2.0格式，需先转换为OpenAPI 3.x格式（SpringDoc仅支持3.x规范）。
• 确保yaml文件路径正确，若文件不在resources目录下，可改用绝对路径或其他方式加载输入流。

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