파라미터 위치에 맞지 않는 allowReserved 설정

설명

OpenAPI 3.0에서 Parameter 객체의 allowReserved는 query 파라미터에 예약 문자를 퍼센트 인코딩하지 않고 포함할 수 있는지를 설명합니다. path, header, cookie 파라미터에는 적용되지 않습니다.

잠재적 영향

API 사용자가 경로 값의 인코딩 규칙을 잘못 이해할 수 있습니다.
클라이언트와 서버가 예약 문자를 다르게 해석하면 요청 값이나 대상 경로가 달라질 수 있습니다.

해결 방법

Parameter 객체의 allowReserved는 query 파라미터에서만 사용하세요. 다른 위치에서는 제거하고 실제 값의 인코딩 규칙을 명확히 정하세요. 속성을 적용하려고 파라미터 위치를 임의로 바꾸지 말고, 실제 API 경로와 클라이언트 요청이 일치하는지 확인하세요.

예시

경로의 id 파라미터를 비교하는 발췌문입니다. /users/{id} 작업의 응답 정의는 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API overview",
    "version": "1.0.0"
  },
  "paths": {
    "/{id}": {
      "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"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "ID of the API the version",
          "required": true,
          "allowReserved": true,
          "schema": {
            "type": "integer"
          }
        }
      ]
    },
    "/users/{id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "allowReserved": true,
            "description": "The user ID",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ]
      }
    }
  }
}

변경 후