Description
A response header’s $ref must point to a Header Object describing its format and meaning. Referencing another kind of definition, such as a Response Object, prevents the header from being interpreted correctly.
Potential impact
Header information may be missing from documentation, or specification validation and client generation may fail.
Remediation
Reference the correct shared header under #/components/headers/.... External files are also supported when they provide a valid Header Object.
Examples
These examples correct the RateLimit reference path from responses to headers.
Before
json
{
"openapi": "3.0.0",
"info": {"title": "Rate Limit API", "version": "1.0.0"},
"paths": {
"/status": {
"get": {
"responses": {
"200": {
"description": "OK",
"headers": {
"X-Rate-Limit-Limit": {
"$ref": "#/components/responses/RateLimit"
}
}
}
}
}
}
},
"components": {
"headers": {
"RateLimit": {
"description": "Requests allowed per hour",
"schema": {"type": "integer"}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {"title": "Rate Limit API", "version": "1.0.0"},
"paths": {
"/status": {
"get": {
"responses": {
"200": {
"description": "OK",
"headers": {
"X-Rate-Limit-Limit": {
"$ref": "#/components/headers/RateLimit"
}
}
}
}
}
}
},
"components": {
"headers": {
"RateLimit": {
"description": "Requests allowed per hour",
"schema": {"type": "integer"}
}
}
}
}