merge-openapi-specs
Use speakeasy merge to combine multiple specs into one.
When to Use
- Combining microservice specs into a unified API
- Merging versioned spec files
- Combining public and internal API specs
- User says: "merge specs", "combine specs", "multiple OpenAPI files"
Inputs
| Input | Required | Description |
|---|
| OpenAPI specs | Yes (2+) | Specs to merge (-s for each) |
Outputs
| Output | Description |
|---|
| Merged spec | Combined OpenAPI spec (-o) |
Command
speakeasy merge -s <spec1> -s <spec2> -o <output-path>
Example
# 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
Use Cases
- Microservices with separate specs per service
- API versioning with multiple spec files
- Combining public and internal API specs
Conflict Resolution
When specs have conflicts:
- Later specs override earlier ones for duplicate paths
- Schema conflicts may require manual resolution
- Review merged output for correctness
Troubleshooting
| Error | Cause | Solution |
|---|
| Schema conflicts | Duplicate schema names | Rename schemas before merging |
| Missing references | Cross-spec $ref | Ensure all referenced schemas are included |
| Duplicate paths | Same endpoint in multiple specs | Remove duplicates or use different base paths |
Related Skills
validate-openapi-spec - Validate merged outputstart-new-sdk-project - Generate SDK from merged speccreate-openapi-overlay - Customize merged spec without editing
