Description
OpenAPI 3.0 allows operations to reuse parameter definitions from components.parameters through $ref. A missing target can leave the input location, type or required status unclear in the documentation.
Potential impact
- API users may omit a needed parameter or send it in the wrong format.
- Reference errors can prevent specification validation or client generation.
Remediation
Check that each parameter $ref points to the intended Parameter Object. Match local references exactly to names in components.parameters, and update all uses when renaming a definition. Validate the references and input definitions after changes.
Examples
The first example uses wrongParameter, which is not defined.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
},
"parameters": [
{
"$ref": "#/components/parameters/wrongParameter"
}
]
}
}
},
"components": {
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"description": "max records to return",
"required": true,
"schema": {
"type": "integer"
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
},
"parameters": [
{
"$ref": "#/components/parameters/limitParam"
}
]
}
}
},
"components": {
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"description": "max records to return",
"required": true,
"schema": {
"type": "integer"
}
}
}
}
}
The second example references limitParam, defining limit as a required integer query parameter. The server’s actual input validation should agree with this contract.