docs agent's openapi merge lost path parameters from the second spec
Fixes OpenAPI merges that drop path parameters from one of the merged specs. Use when merged output is missing path-level parameters. Not for schema validation errors.
TL;DR
Merge at the paths level with a tool that understands OpenAPI semantics (like redocly bundle), and verify parameters after the merge. Naive deep-merges overwrite one spec's path item with the other's.
Error
(merged spec missing the {id} path parameter on /orders; clients fail; no lint error)Steps
- Diff the merged spec's paths against each input spec's paths, focusing on the parameters arrays at path and operation level. Expected: the dropped parameters identified.
- Check the merge method: object spread or generic deep-merge of path items replaces arrays instead of combining them. Expected: the lossy merge step found.
- Switch to
redocly bundle(or an equivalent OpenAPI-aware merge) which combines path items correctly, or write the merge to concatenate parameters arrays with dedup by name and location. Expected: a semantics-aware merge. - Re-merge and re-diff. Expected: parameters from both specs present.
When to use
- Merged OpenAPI is missing parameters from one input
- Specs are split by team or service and merged in CI
- A docs agent concatenates spec files
When not to use
- The parameter is missing from the input spec too (an authoring gap)
- The merge duplicates rather than drops (a different merge bug)
- You intentionally override parameters (document the override)
Tool compatibility
Redocly CLI bundle, or custom merge scripts. The array-replacement pitfall is tool-independent.
Variant phrasings
merge lost operation-level parameters too
Same fix: concatenate and dedupe the parameters arrays instead of replacing them.
parameters duplicated after switching merge tools
Dedupe by the (name, in) pair; the same parameter defined at path and operation level is legal but redundant.
Why it happens
Generic deep-merge treats the parameters array as a single value and the second spec wins wholesale. OpenAPI semantics require set-union on parameters, which only a spec-aware merge does.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_Sh5wMnFuFaaDqTb3K0IsBA