説明
OpenAPI 3.0のHeader Objectは、schemaまたはcontentのどちらかで値の形式を定義します。どちらもないと、クライアントは数値や文字列などの型と表現方法を正しく判断しにくくなります。
想定される影響
文書ツールやSDKがヘッダーの型を適切に扱えなかったり、クライアントが値を誤って解釈したりする可能性があります。
対処方法
一般的なヘッダー値は、実際の型と必要な制約をschemaに定義してください。メディアタイプを指定する表現にはcontentを使用し、両方を同時に定義しないでください。共通の定義を参照する場合は、参照先の形式を確認します。
例
この例では、レスポンスヘッダーX-Rate-Limit-Limitの値を整数として定義しています。
変更前
json
{
"openapi": "3.0.0",
"components": {
"responses": {
"ResponseExample": {
"headers": {
"X-Rate-Limit-Limit": {
"description": "The number of allowed requests in the current period"
}
}
}
}
}
}
変更後
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"
}
}
}
}
}
}
}