説明
OpenAPI 3.0 の encoding.allowReserved は、application/x-www-form-urlencoded のリクエスト本文に適用されます。他のメディアタイプでは、このプロパティで予約文字のエンコード方法を指定できません。
想定される影響
- API 利用者が予約文字をそのまま送信できると誤解する可能性があります。
- クライアントとサーバーでエンコードの解釈が異なると、受け取る値が変わることがあります。
対処方法
encoding.allowReserved は application/x-www-form-urlencoded の本文でのみ使用してください。他の形式では削除し、その形式のエンコード規則に従ってください。メディアタイプを変更する場合は API とクライアントも合わせて変更し、予約文字の処理を確認してください。
例
以下はリクエスト本文 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",
"allowReserved": 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",
"allowReserved": true
}
}
}
}
}
}
}
}
変更後は allowReserved が適用される URL エンコード形式のフォームを使用しています。multipart のファイルアップロードとは送信形式が異なるため、文書だけを変更せず、実際の API が対応していることを確認してください。