Encoding 객체의 allowReserved 적용 범위 점검

설명

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가 이 형식을 지원하는지 확인하세요.