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

설명

상태 코드별 응답의 $ref는 응답 객체를 가리켜야 합니다. 데이터 스키마만으로는 응답 설명, 헤더, 본문 형식을 포함하는 응답 객체를 대신할 수 없습니다.

잠재적 영향

명세 검증이나 문서 생성이 실패하거나 클라이언트가 응답 형식을 잘못 이해할 수 있습니다.

해결 방법

공통 응답은 #/components/responses/...에서 참조하고 본문 스키마는 응답의 content 안에 지정하세요. 유효한 외부 응답 객체도 사용할 수 있습니다.

예시

다음 예시는 Success의 참조 경로를 schemas에서 responses로 수정합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "components": {
    "responses": {
      "Success": {
        "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"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/components/schemas/Success"
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "components": {
    "responses": {
      "Success": {
        "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"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/": {
      "get": {
        "operationId": "listVersionsv2",
        "summary": "List API versions",
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  }
}