collectionFormat: multi의 위치 오류 (OpenAPI 2.0)

설명

collectionFormat: multi는 같은 이름의 매개변수를 반복해 배열을 보내는 방식입니다. OpenAPI 2.0에서는 query와 formData에서만 사용할 수 있습니다.

잠재적 영향

클라이언트가 서버와 다른 방식으로 배열을 직렬화해 요청이 실패할 수 있습니다.

해결 방법

매개변수의 위치와 실제 요청 형식에 맞는 직렬화를 선택하세요. path나 header 배열은 csv 같은 지원되는 형식을 사용하고, 위치를 바꾸려면 서버의 요청 계약에도 맞춰야 합니다.

예시

다음 예시는 limit2를 query로 옮겨 multi를 사용합니다. 별도의 재사용 path 정의인 limitParam에는 csv를 지정합니다.

변경 전

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/{limit2}": {
      "get": {
        "parameters": [
          {
            "name": "limit2",
            "in": "path",
            "description": "max records to return",
            "required": true,
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int64"
            },
            "collectionFormat": "multi"
          }
        ],
        "operationId": "listVersionsV2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "path",
      "description": "max records to return",
      "required": true,
      "type": "array",
      "items": {
        "type": "integer",
        "format": "int64"
      },
      "collectionFormat": "multi"
    }
  }
}

변경 후