如何在Maven生成源码阶段合并无引用关系的多份OpenAPI规范？

完全可以在Maven编译阶段完成多个OpenAPI YAML的合并，针对你的需求（合并paths和components节点），推荐以下几种可行方案：

方案1：使用OpenAPITools的openapi-maven-plugin #

这个插件专门支持OpenAPI规范的处理，包括合并多个独立的规范文件，会自动合并paths和components节点（注意同名组件会被后续文件的内容覆盖，需提前规避命名冲突）。

在pom.xml中添加插件配置，绑定到合适的阶段（比如process-resources，确保generate-sources阶段生成的YAML已存在）：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-maven-plugin</artifactId>
    <version>5.4.0</version> <!-- 使用最新稳定版本 -->
    <executions>
        <execution>
            <id>merge-openapi-specs</id>
            <phase>process-resources</phase>
            <goals>
                <goal>merge</goal>
            </goals>
            <configuration>
                <!-- 列出所有需要合并的OpenAPI YAML文件路径 -->
                <inputSpecs>
                    <inputSpec>${project.build.directory}/generated-sources/openapi/api1.yaml</inputSpec>
                    <inputSpec>${project.build.directory}/generated-sources/openapi/api2.yaml</inputSpec>
                    <inputSpec>${project.build.directory}/generated-sources/openapi/api3.yaml</inputSpec>
                </inputSpecs>
                <!-- 合并后的输出文件路径 -->
                <outputSpec>${project.build.outputDirectory}/META-INF/openapi/merged-api.yaml</outputSpec>
                <!-- 可选：指定合并后的OpenAPI版本，若各文件版本一致可省略 -->
                <openapiVersion>3.0.3</openapiVersion>
            </configuration>
        </execution>
    </executions>
</plugin>

方案2：使用maven-antrun-plugin自定义合并逻辑 #

如果需要更灵活的合并规则（比如处理组件冲突时自定义策略），可以用antrun插件调用脚本（比如Python/Shell脚本）完成YAML合并。

1. 先写一个简单的Python合并脚本（比如merge_openapi.py，放在项目根目录的scripts文件夹下）：

import yaml
import glob
import os

def merge_openapi_files(input_pattern, output_path):
    merged = {"openapi": "3.0.3", "paths": {}, "components": {}}
    # 遍历所有匹配的YAML文件
    for file_path in glob.glob(input_pattern):
        with open(file_path, 'r') as f:
            spec = yaml.safe_load(f)
            # 合并paths
            if spec.get("paths"):
                merged["paths"].update(spec["paths"])
            # 合并components的各个子节点（schemas、responses等）
            if spec.get("components"):
                for comp_type, comps in spec["components"].items():
                    if comp_type not in merged["components"]:
                        merged["components"][comp_type] = {}
                    merged["components"][comp_type].update(comps)
    # 写入合并后的文件
    with open(output_path, 'w') as f:
        yaml.dump(merged, f, sort_keys=False)

if __name__ == "__main__":
    input_pattern = "target/generated-sources/openapi/*.yaml"
    output_path = "target/classes/META-INF/openapi/merged-api.yaml"
    os.makedirs(os.path.dirname(output_path), exist_ok=True)
    merge_openapi_files(input_pattern, output_path)

2. 在pom.xml中配置antrun插件执行该脚本：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-antrun-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <id>merge-openapi-scripts</id>
            <phase>process-resources</phase>
            <goals>
                <goal>run</goal>
            </goals>
            <configuration>
                <tasks>
                    <exec executable="python3">
                        <arg value="${project.basedir}/scripts/merge_openapi.py"/>
                    </exec>
                </tasks>
            </configuration>
        </execution>
    </executions>
</plugin>

方案3：自定义Maven插件（适合高度定制需求） #

如果上述方案都不符合你的需求，可以自己写一个简单的Maven插件（Mojo）：

• 读取指定目录下的所有OpenAPI YAML文件
• 使用OpenAPI官方的openapi-parser库解析每个规范
• 手动合并paths和components节点
• 将合并后的规范写入目标文件

这种方式可控性最强，但需要具备基础的Java和Maven插件开发能力。

注意事项 #

• 合并阶段选择：确保插件绑定的阶段在generate-sources之后（比如process-resources或compile），保证所有待合并的YAML文件已生成。
• 冲突处理：若多个规范中有同名的components（比如同名Schema），合并时会被后续文件的内容覆盖，建议提前统一命名规则避免冲突。

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