Description
In OpenAPI 3.0 and Swagger 2.0, each name and in pair must be unique within a parameter list. Duplicates in that list can disrupt interpretation, but separate keys in a reusable definition map may describe the same pair. An operation can also override a path-level parameter with the same identity.
Potential impact
Duplicates in one list can cause validation or generation errors. Unnecessarily renaming valid reusable definitions can instead break the consumer’s parameter contract.
Remediation
Resolve references and check each path or operation’s parameters list for duplicate pairs. Preserve intentional operation-level overrides. Rename inputs only when genuinely separate inputs are required, updating the client and server contract together.
Examples
These excerpts show OpenAPI 3.0 reusable parameter components only. Actual path or operation usage lists and info are omitted.
Before
{
"openapi": "3.0.0",
"components": {
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
},
"otherLimitParam": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
}
}
}
}
After
{
"openapi": "3.0.0",
"components": {
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
},
"offsetParam": {
"name": "offset",
"in": "query",
"schema": {
"type": "integer"
}
}
}
}
}
The two before components defining limit/query are not, by themselves, a duplicate-use error. The after example defines a separate offset input and is appropriate only if the API supports it. What matters is how definitions are used in the same request list.