説明
OpenAPI 3.0 の encoding.explode は、application/x-www-form-urlencoded のリクエスト本文で配列やオブジェクトの値をどう直列化するかを記述します。他のメディアタイプには適用されず、文字列など配列でもオブジェクトでもない値には効果がありません。
想定される影響
- API 利用者が配列やオブジェクトのフィールドの送信方法を誤解する可能性があります。
- サーバーの想定と異なる直列化により、値が欠落したりリクエストが失敗したりすることがあります。
対処方法
application/x-www-form-urlencoded の本文で必要な配列やオブジェクトの直列化に合わせて encoding.explode を設定してください。他のメディアタイプでは削除し、その形式の規則に従ってください。メディアタイプを変更する場合は、クライアントとサーバーの対応を確認し、実際のリクエストを試験してください。
例
以下はリクエスト本文 NewItem の定義の抜粋です。これを使用する操作と tshirt の例の定義は省略しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
],
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0"
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"requestBodies": {
"NewItem": {
"description": "Item data",
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "binary"
}
}
},
"examples": {
"tshirt": {
"$ref": "#/components/examples/tshirt"
}
},
"encoding": {
"code": {
"contentType": "image/png, image/jpeg",
"explode": true
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
],
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0"
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"requestBodies": {
"NewItem": {
"description": "Item data",
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "binary"
}
}
},
"examples": {
"tshirt": {
"$ref": "#/components/examples/tshirt"
}
},
"encoding": {
"code": {
"contentType": "image/png, image/jpeg",
"explode": true
}
}
}
}
}
}
}
}
変更後のメディアタイプでは explode を使用できます。ただし、この例の code は文字列なので、explode によって表現は変わりません。実際の API 契約で配列やオブジェクトを使う場合は、その値の直列化を別途確認してください。