본문 외 매개변수에 schema 사용 (OpenAPI 2.0)

설명

OpenAPI 2.0의 query, path, header, formData 매개변수는 schema 대신 매개변수 수준의 type으로 타입을 정의합니다. 배열에는 items도 필요합니다.

잠재적 영향

문서 검증이 실패하거나 도구가 매개변수의 타입을 제대로 해석하지 못할 수 있습니다.

해결 방법

schema를 제거하면서 실제 타입을 type으로 옮기고, 필요한 format이나 items도 매개변수에 직접 정의하세요. schema만 삭제해 타입까지 누락하지 마세요.

예시

다음 예시는 query 매개변수와 재사용 가능한 path 매개변수에서 schema 대신 type: integer를 사용합니다. limitParam은 이 작업에서 참조하지 않는 정의입니다.

변경 전

json

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

변경 후

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "get": {
        "parameters": [
          {
            "name": "limit2",
            "in": "query",
            "description": "max records to return",
            "required": true,
            "type": "integer"
          }
        ],
        "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": "integer"
    }
  }
}