응답 본문 Schema 없음

설명

응답 본문의 구조가 정의되어 있지 않으면 클라이언트가 반환 데이터를 어떻게 처리해야 하는지 알기 어렵습니다. 본문이 없는 응답에 스키마를 추가할 필요는 없으며, 본문 유무는 실제 API 계약에 따라 판단해야 합니다.

잠재적 영향

클라이언트의 파싱 오류나 잘못된 SDK 모델로 이어지고, 응답 구조 변경에 따른 호환성 문제를 발견하기 어려워질 수 있습니다.

해결 방법

본문 구조를 명시할 때 OpenAPI 3.0에서는 응답의 content 아래에 미디어 유형과 schema를 정의하십시오. OpenAPI 2.0에서는 응답의 schema와 적용되는 produces를 사용합니다. 실제 반환 데이터와 문서가 일치하도록 유지하십시오.

예시

예시는 OpenAPI 3.0의 JSON 응답을 공통 ApiVersion 스키마로 설명합니다. 참조 대상의 정의는 이 발췌에서 생략했습니다.

변경 전

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "200 response"
          }
        }
      }
    }
  }
}

변경 후

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "200 response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiVersion"
                }
              }
            }
          }
        }
      }
    }
  }
}