Description
Missing required properties in an OpenAPI 2.0 object can prevent specification validation, documentation generation or client generation. Required properties depend on the object type and its configuration.
For example, info requires title and version. Body parameters require schema, while non-body parameters require type. Required security-definition properties also depend on the authentication method.
Potential impact
- Specification validation or code generation may fail.
- Incomplete input and response definitions can lead API consumers and implementers to interpret the contract differently.
Remediation
Check the OpenAPI 2.0 requirements and conditions for each object, and add values that describe the actual API. Align the contract with the implementation rather than filling fields arbitrarily, then validate the revised specification.
Examples
The first document omits info.version and type for a query parameter.
Before
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
}
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"description": "max records to return",
"required": true
}
}
}
After
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
}
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "query",
"description": "max records to return",
"required": true,
"type": "string"
}
}
}
The second document adds both required properties. Use values that reflect the actual parameter type and API version.