Description
An OpenAPI 3.0 Header Object defines its value through either schema or content. Without either, clients cannot reliably determine the type and representation, such as a number or string.
Potential impact
Documentation tools or SDKs may mishandle the header type, or clients may interpret its value incorrectly.
Remediation
For ordinary header values, define the actual type and necessary constraints in schema. Use content for a representation with a media type, and choose only one of these approaches. If using a shared reference, check the referenced definition.
Examples
The example defines the response header X-Rate-Limit-Limit as an integer.
Before
json
{
"openapi": "3.0.0",
"components": {
"responses": {
"ResponseExample": {
"headers": {
"X-Rate-Limit-Limit": {
"description": "The number of allowed requests in the current period"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"components": {
"responses": {
"ResponseExample": {
"headers": {
"X-Rate-Limit-Limit": {
"description": "The number of allowed requests in the current period",
"schema": {
"type": "integer"
}
}
}
}
}
}
}