배열 항목 정의 누락

설명

OpenAPI 3.0과 Swagger 2.0에서 스키마를 array 타입으로 선언했다면 배열에 어떤 값이 들어가는지 items로 함께 정의해야 합니다. 이 설정이 없으면 문서 검증이나 코드 생성이 실패하고 배열 내부 구조를 일관되게 해석하기 어렵습니다.

잠재적 영향

배열 요소의 타입이 불명확해져 API 사용자가 요청과 응답 형식을 잘못 이해하거나 연동 오류가 발생할 수 있습니다.

해결 방법

배열 스키마에 items를 정의해 요소의 타입 또는 참조 스키마를 지정하세요. OpenAPI 3.0 파라미터는 스키마 안에, Swagger 2.0의 본문 이외 배열 파라미터는 파라미터 자체에 items를 설정하세요.

예시

OpenAPI 3.0 스키마 발췌입니다. 완전한 문서에 필요한 info와 paths는 생략했습니다.

변경 전

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

변경 후

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

변경 전에는 배열 요소 정의가 없습니다. 변경 후는 items.type: string으로 문자열 배열을 명시합니다. 실제 요청과 응답도 이 형식에 맞는지 확인하세요.

참조

• OpenAPI Specification - Schema Object
• CWE-665: Improper Initialization
• OpenAPI 3.0 스키마 정의
• Swagger 2.0 파라미터 정의