## 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
```text
(merged spec missing the {id} path parameter on /orders; clients fail; no lint error)
```

## Steps
1. 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.
2. 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.
3. 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.
4. 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