잘못된 응답 객체 참조 (OpenAPI 2.0)

설명

작업의 응답 위치에 있는 $ref는 응답 객체를 가리켜야 합니다. 본문 스키마만으로는 응답 설명이나 헤더 등을 포함하는 응답 객체를 대신할 수 없습니다.

잠재적 영향

응답 정의의 검증이나 문서 생성에 실패하고 클라이언트가 응답 계약을 잘못 이해할 수 있습니다.

해결 방법

공통 응답은 #/responses/...에서 참조하고, 본문 모델은 응답의 schema 안에서 참조하세요. 외부 파일도 유효한 응답 객체를 제공하면 사용할 수 있습니다.

예시

다음 POST 예시는 응답 위치의 User 스키마 참조를 Success 응답 참조로 바꿉니다.

변경 전

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/definitions/User"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/limitParam"
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "A user",
      "schema": {
        "$ref": "#/definitions/User"
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "body",
      "description": "max records to return",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}

변경 후

json

{
  "swagger": "2.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/": {
      "post": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/responses/Success"
          }
        },
        "parameters": [
          {
            "$ref": "#/parameters/limitParam"
          }
        ]
      }
    }
  },
  "responses": {
    "Success": {
      "description": "A user",
      "schema": {
        "$ref": "#/definitions/User"
      }
    }
  },
  "parameters": {
    "limitParam": {
      "name": "limit",
      "in": "body",
      "description": "max records to return",
      "required": true,
      "schema": {
        "type": "integer"
      }
    }
  },
  "definitions": {
    "User": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
}