Description
Defining a parameter in components.parameters does not apply it to a request. Reference it from a path or operation’s parameters; unused definitions can be reviewed for cleanup.
Potential impact
Readers may assume that the API accepts a parameter that is not part of the operation.
Remediation
Reference needed parameters with $ref where they are used. Match names, locations, and requiredness to the API, and remove unnecessary definitions only after checking use by other documents.
Examples
These examples reference limitParam from the operation’s parameters.
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"
}
}
}
}
},
"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"
}
}
}
}
}