한 작업에 body와 formData 혼용 (OpenAPI 2.0)

설명

OpenAPI 2.0의 한 작업에서는 in: body와 in: formData를 함께 사용할 수 없습니다. 두 방식 모두 요청 본문을 표현하므로 하나만 선택해야 합니다.

잠재적 영향

명세 검증에 실패하거나 클라이언트가 서버와 다른 형식으로 본문을 구성할 수 있습니다.

해결 방법

실제 요청 형식에 맞춰 단일 body 매개변수 또는 formData 매개변수들을 사용하세요. 폼 전송에는 적절한 consumes를 지정하고 각 매개변수에 타입을 정의하세요.

예시

다음 POST 예시는 혼용된 본문·폼 매개변수를 폼 매개변수로 통일합니다. 폼의 전송 형식과 정수 타입을 명시하며, 실제 API도 이 형식에 맞게 구성해야 합니다.

변경 전

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response"
          }
        },
        "parameters": [
          {
            "name": "limit2",
            "in": "body",
            "description": "max records to return",
            "required": true,
            "schema": {
              "type": "object"
            }
          },
          {
            "name": "minlimit",
            "in": "formData",
            "description": "min records to return",
            "required": true,
            "type": "integer"
          }
        ],
        "consumes": [
          "application/x-www-form-urlencoded"
        ]
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "formData",
      "description": "max records to return",
      "required": true,
      "type": "integer"
    }
  }
}

변경 후