本文介绍一种基于 swagger core 的 java 实现方案，用于在 maven 插件中聚合多个无依赖关系的 openapi v3 文件（如 component-descriptor.yaml），仅合并 paths、components/parameters 和 components/schemas，并输出为标准化 yaml 文件。
本文介绍一种基于 swagger core 的 java 实现方案，用于在 maven 插件中聚合多个无依赖关系的 openapi v3 文件（如 component-descriptor.yaml），仅合并 paths、components/parameters 和 components/schemas，并输出为标准化 yaml 文件。
在微服务或模块化 Java 项目中，各模块常维护独立的 OpenAPI 描述文件（如 component-descriptor.yaml），彼此无引用关系（不使用 $ref），也无法通过 OpenAPI 原生机制联动。当构建主模块时，需将所有直接依赖模块的 API 路径统一聚合到当前项目的 OpenAPI 文件中——这并非文档渲染或运行时合并，而是构建期的静态合成任务。
实现该目标的核心思路是：解析 → 合并 → 序列化。整个流程完全基于 Swagger Core（swagger-parser-v3）和 Jackson YAML 支持，无需外部工具或模板引擎。
✅ 步骤一：解析多个 OpenAPI 文件为 Java 对象
使用 OpenAPIV3Parser 逐个读取 YAML 文件，并校验解析结果：
private final OpenAPIV3Parser parser = new OpenAPIV3Parser();
private OpenAPI parseOpenAPI(FileLocation fileLocation) throws MojoFailureException {
SwaggerParseResult result = parser.readLocation(fileLocation.getUri().toString(), null, null);
if (result == null || result.getOpenAPI() == null) {
throw new MojoFailureException("Failed to parse OpenAPI file: " + fileLocation);
}
return result.getOpenAPI();
}⚠️ 注意：确保 Maven 插件依赖已正确引入 io.swagger.parser.v3:swagger-parser:2.1.2+ 及 io.swagger.core.v3:swagger-models:2.2.20+。
✅ 步骤二：安全合并路径与组件
关键在于避免空指针与重复覆盖。主 OpenAPI 对象作为聚合容器，需主动初始化 Components 和 Paths（若为空）；对每个依赖文件，仅提取其 paths、parameters 和 schemas，追加至主对象对应集合：
private OpenAPI aggregateOpenAPI(FileLocation mainFile, List<FileLocation> dependencyFiles)
throws IOException, MojoFailureException {
OpenAPI base = parseOpenAPI(mainFile);
// 确保基础对象具备必要结构
base.setPaths(base.getPaths() != null ? base.getPaths() : new Paths());
base.setComponents(base.getComponents() != null ? base.getComponents() : new Components());
for (FileLocation dep : dependencyFiles) {
OpenAPI depApi = parseOpenAPI(dep);
// 合并 paths（按 path + method 去重由 OpenAPI 规范保证，此处直接 add）
depApi.getPaths().forEach((path, pathItem) -> base.getPaths().addPathItem(path, pathItem));
// 合并 components
Components depComponents = depApi.getComponents();
if (depComponents != null) {
if (depComponents.getParameters() != null) {
depComponents.getParameters().forEach(base.getComponents()::addParameters);
}
if (depComponents.getSchemas() != null) {
depComponents.getSchemas().forEach(base.getComponents()::addSchemas);
}
}
}
return base;
}? 提示：Paths.addPathItem(String, PathItem) 会自动处理路径冲突（同路径同方法时后者覆盖前者）。如需严格去重或冲突告警，可先遍历检查 base.getPaths().get(path) 是否已存在。
✅ 步骤三：序列化为标准 YAML 文件
Swagger Core 内置 Yaml 工具类支持将 OpenAPI 对象直接格式化为美观、符合 OpenAPI 规范的 YAML 字符串：
String yamlContent = Yaml.pretty(aggregateOpenAPI);
Files.writeString(Paths.get("target/component-descriptor.yaml"), yamlContent, StandardCharsets.UTF_8);- 使用 Yaml.pretty() 而非 Yaml.mapper() 可自动注入 OpenAPI 所需的 openapi: "3.1.0"、缩进、锚点等语义化格式；
- 务必用 Files.writeString(..., UTF_8) 替代 Files.write(..., getBytes())，避免中文等 Unicode 字符乱码；
- 若需 JSON 输出，替换为 Json.pretty(aggregateOpenAPI) 即可。
✅ 补充建议与注意事项
- 版本一致性：确保所有输入 OpenAPI 文件均为 v3.x（推荐 v3.1.0），混合 v2/v3 将导致解析失败；
- 扩展字段保留：上述逻辑未合并 info、tags、servers 等顶层字段，如需保留主文件元信息，可显式复制 base.setInfo(depApi.getInfo()) 等；
- Schema 命名冲突：addSchemas(String, Schema) 在键重复时会覆盖。建议在聚合前对依赖模块的 schema 名称添加命名空间前缀（如 depA_User），可通过遍历 depComponents.getSchemas() 并重命名 key 实现；
- Maven 生命周期集成：将此逻辑封装为 Mojo 的 execute() 方法，在 process-classes 阶段执行，确保依赖 JAR 中的 component-descriptor.yaml 已解压可用。
通过以上三步，即可在构建过程中自动化、可靠地完成多源 OpenAPI 路径聚合，为统一网关配置、API 文档中心或契约测试提供坚实的数据基础。
