merge-openapi-specs

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 output
• start-new-sdk-project - Generate SDK from merged spec
• create-openapi-overlay - Customize merged spec without editing