OpenAPI 3.0 encoding 키와 스키마 속성 불일치

설명

OpenAPI 3.0의 encoding은 multipart 또는 application/x-www-form-urlencoded 요청 본문의 속성별 직렬화 설정입니다. encoding 키는 해당 스키마에 정의된 속성 이름이어야 합니다. 없는 속성의 설정은 의도한 입력에 적용할 수 없습니다.

잠재적 영향

입력 속성에 필요한 콘텐츠 유형이나 직렬화 설정이 반영되지 않을 수 있습니다.
도구 검증이 실패하거나 클라이언트와 서버가 입력을 다르게 처리할 수 있습니다.

해결 방법

encoding의 각 키를 스키마의 properties에 정의된 이름과 맞추세요. 사용하지 않는 항목은 제거하고, 속성 이름을 바꿀 때 관련 인코딩과 예제도 갱신하세요. 실제 요청이 의도한 방식으로 직렬화되는지 확인하세요.

예시

다음은 재사용할 multipart 요청 본문의 일부입니다. 사용할 작업의 requestBody 참조는 별도로 연결해야 합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "https://www.google.com/",
      "email": "user@gmail.c"
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "requestBodies": {
      "ResponseExample": {
        "description": "Upload body",
        "content": {
          "multipart/form-data": {
            "schema": {
              "properties": {
                "code": {
                  "type": "string",
                  "format": "binary"
                },
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "encoding": {
              "profileImage": {
                "contentType": "image/png, image/jpeg"
              }
            }
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0",
    "contact": {
      "name": "contact",
      "url": "https://www.google.com/",
      "email": "user@gmail.c"
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "requestBodies": {
      "ResponseExample": {
        "description": "Upload body",
        "content": {
          "multipart/form-data": {
            "schema": {
              "properties": {
                "code": {
                  "type": "string",
                  "format": "binary"
                },
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "encoding": {
              "code": {
                "contentType": "image/png, image/jpeg"
              }
            }
          }
        }
      }
    }
  }
}

변경 후에는 스키마에 없는 profileImage 대신 code에 인코딩을 지정합니다. 이 설정은 multipart 요청의 해당 속성에 적용되며 JSON 응답을 제어하지 않습니다.