説明
OpenAPI 3.0では、レスポンスのheaders内に定義したContent-Typeは無視され、本文形式はcontentで表します。AcceptやAuthorizationという名前だけで、すべてのレスポンスヘッダーが一律に禁止されるわけではないため、実際のHTTP上の意味と契約を確認してください。
想定される影響
本文形式の誤記や標準ヘッダーの業務データへの転用により、生成されたクライアントと実際のレスポンスが一致しない場合があります。
対処方法
メディアタイプはOpenAPI 3.0のレスポンスのcontent、またはSwagger 2.0のproducesで記述してください。他のヘッダーはサーバーが実際に返す名前と値の形式に合わせ、標準ヘッダーの意味を勝手に変更しないでください。
例
OpenAPI 3.0でContent-Typeの定義と、独立したPetヘッダーを比較します。Petは業務メタデータが実際に必要な場合の例であり、本文形式のヘッダーを単に改名したものではありません。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"500": {
"description": "500 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "400 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"500": {
"description": "500 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
},
"400": {
"description": "400 response",
"headers": {
"Pet": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
変更後もJSON本文の形式はcontent.application/jsonで定義しています。Petが必要なら、サーバーは実際にその文字列ヘッダーを返す必要があります。