Encoding 객체의 explode 적용 범위 점검

설명

OpenAPI 3.0의 encoding.explode는 application/x-www-form-urlencoded 요청 본문의 배열이나 객체 값을 어떻게 직렬화할지 설명합니다. 다른 미디어 타입에서는 적용되지 않으며, 문자열 등 배열이나 객체가 아닌 값에는 효과가 없습니다.

잠재적 영향

API 사용자가 배열이나 객체 필드의 전송 방식을 잘못 이해할 수 있습니다.
직렬화 방식이 서버의 기대와 다르면 일부 값이 누락되거나 요청이 실패할 수 있습니다.

해결 방법

encoding.explode는 application/x-www-form-urlencoded 본문에서 배열이나 객체의 직렬화 요구에 맞춰 설정하세요. 다른 미디어 타입에서는 제거하고 해당 형식의 규칙을 따르세요. 미디어 타입을 변경하면 클라이언트와 서버의 지원을 함께 확인하고 실제 요청을 시험하세요.

예시

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
              }
            }
          }
        }
      }
    }
  }
}

변경 후