用途
merge-openapi-specs 用于将多个 OpenAPI 规范文件合并为一个统一的规范。它基于 speakeasy merge 命令，适合需要把分散的 API 定义整合到单一文件的场景。
主要能力
- 将两个或更多 OpenAPI 规范合并为单个输出文件。
- 支持逐个指定待合并的规范文件。
- 输出合并后的 OpenAPI 规范到指定路径。
使用方式
命令格式：
speakeasy merge -s <spec1> -s <spec2> -o <output-path>
示例：
# Merge two specs
speakeasy merge -s ./api/users.yaml -s ./api/orders.yaml -o combined.yaml
# Merge multiple specs (specify each with -s)
speakeasy merge -s ./specs/auth.yaml -s ./specs/users.yaml -s ./specs/orders.yaml -o combined.yaml
输入要求：至少两个 OpenAPI 规范，每个通过 -s 参数指定。
输出：合并后的 OpenAPI 规范，通过 -o 参数指定输出路径。
适用场景
- 将微服务各自的规范合并为统一 API。
- 合并不同版本的规范文件。
- 组合公开与内部 API 规范。
- 用户提到“merge specs”“combine specs”“multiple OpenAPI files”等表述时。
冲突处理
当规范之间存在冲突时：
- 对于重复路径，后指定的规范会覆盖先前的规范。
- schema 冲突可能需要手动解决。
- 建议检查合并后的输出以确保正确性。
故障排查
| 错误 | 原因 | 解决方案 |
|---|---|---|
| Schema conflicts | 重复的 schema 名称 | 合并前重命名 schema |
| Missing references | 跨规范 $ref 引用 | 确保所有被引用的 schema 都已包含 |
| Duplicate paths | 多个规范中存在相同端点 | 移除重复项或使用不同的基础路径 |
相关技能
- validate-openapi-spec：验证合并后的输出。
- start-new-sdk-project：从合并后的规范生成 SDK。
- create-openapi-overlay：在不直接编辑的情况下定制合并后的规范。
限制
资料未提供关于收费、价格、平台支持范围或具体性能效果的信息。