스키마 타입과 items 용도 점검

설명

items는 배열 요소를 설명하는 속성입니다. 객체나 문자열 스키마에 이를 추가해도 객체 필드나 문자열 내용을 제한하지 않습니다. 실제 데이터 타입과 맞지 않는 키워드는 API 계약을 오해하게 할 수 있습니다.

잠재적 영향

문서 소비자가 의도한 검증이 적용된다고 오해하거나, 생성 코드에서 실제 데이터와 다른 자료형을 사용할 수 있습니다.

해결 방법

실제 데이터가 배열이면 type: array와 요소의 items를 정의하세요. 객체라면 properties 등 객체용 제약을 사용하고 관련 없는 items를 제거하세요. 키워드를 맞추기 위해 실제 API의 데이터 타입을 임의로 바꾸지 마세요.

예시

OpenAPI 3.0 스키마 발췌이며 info와 paths는 생략했습니다. 실제 계약이 문자열 배열인 경우를 비교합니다.

변경 전

{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "GeneralError": {
        "type": "object",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

변경 후

{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "GeneralError": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

변경 전의 items는 객체 필드를 문자열로 제한하지 않습니다. 변경 후는 문자열 배열을 선언합니다. 실제 데이터가 객체라면 타입을 바꾸는 대신 객체 속성을 올바르게 정의해야 합니다.

참조

• OpenAPI Specification - Schema Object
• CWE-20: Improper Input Validation
• OpenAPI 3.0 스키마 규칙
• JSON Schema 키워드와 데이터 타입