참조 객체의 추가 속성 점검

설명

OpenAPI 3.0의 Reference Object는 $ref 외에 추가한 속성을 무시합니다. Swagger 2.0의 참조도 같은 JSON Reference 규칙을 따릅니다. 옆에 쓴 type이나 description이 참조 대상을 변경한다고 기대하면 실제 계약과 문서 의도가 달라질 수 있습니다.

이 규칙을 모든 $ref 위치나 다른 명세 버전에 일괄 적용하지 마세요. 예를 들어 Path Item의 $ref는 별도 필드 규칙을 따릅니다.

잠재적 영향

의도한 제약이나 설명이 적용되지 않아 요청·응답 검증과 생성된 클라이언트가 기대와 다를 수 있습니다.

해결 방법

해당 버전의 Reference Object에는 $ref만 남기세요. 추가 설명이나 제약은 참조 대상에 정의하거나, 스키마 위치라면 필요한 제약을 함께 적용하는 allOf 구성을 검토하세요. 참조 대상이 존재하고 제약들이 양립하는지도 확인하세요.

예시

참조 사용 부분만 보여주는 OpenAPI 3.0 발췌입니다. info와 참조 대상 components.schemas.MyObject 정의는 별도로 필요합니다.

변경 전

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "integer",
                  "$ref": "#/components/schemas/MyObject"
                }
              }
            }
          }
        }
      }
    }
  }
}

변경 후

json

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

변경 후는 무시되는 형제 속성 type을 제거합니다. 참조 대상의 타입은 그대로이며, 이 변경이 대상을 정수 타입으로 바꾸지는 않습니다.