説明
レスポンスヘッダーの $ref は、その形式や意味を定義するヘッダーオブジェクトを参照する必要があります。レスポンスオブジェクトなど別の種類の定義を参照すると、ヘッダーを正しく解釈できません。
想定される影響
文書からヘッダー情報が欠落したり、仕様の検証やクライアント生成に失敗したりする可能性があります。
対処方法
共通ヘッダーは #/components/headers/... の正しい定義を参照してください。有効なヘッダーオブジェクトを提供する外部ファイルも使えます。
例
次の例では、RateLimit の参照パスを responses から headers に修正しています。
変更前
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"}
}
}
}
}
変更後
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"}
}
}
}
}