Description
An OpenAPI 2.0 body parameter uses the fields name, in, description, required, and schema. Custom extensions must start with x-; an arbitrary property such as desc is not a standard field.
Potential impact
Document validation may fail, or tools may ignore the property and misinterpret the request body description.
Remediation
Remove invalid properties or move their content to the correct standard field. Use description for explanatory text and schema for body structure. If an extension is needed, use the x- prefix and check tool support.
Examples
These body parameter examples remove the unrecognized desc property. The revised example defines the maximum record count as an integer.
Before
json
{
"name": "limit",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "string"
},
"desc": {
"type": "string"
}
}
After
json
{
"name": "limit",
"in": "body",
"description": "max records to return",
"required": true,
"schema": {
"type": "integer"
}
}