API 다중 파라미터 구조 설계: oneOf, anyOf, allOf 완벽 가이드

API를 설계하다 보면 하나의 엔드포인트가 여러 다른 파라미터 조합을 지원해야 하는 경우가 많습니다. 전통적인 문서화 방식은 단순히 필드를 나열하고 모호한 설명을 추가하는 것이었지만, JSON Schema의 조합 기능을 사용하면 이를 명확하게 정의할 수 있습니다.

세 가지 스키마 조합 방식

allOf: 모든 조건 충족 (AND)

allOf는 모든 규칙이 동시에 충족되어야 합니다. 논리적 AND 연산과 같습니다.

{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" }
      },
      "required": ["id", "name"]
    },
    {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" }
      },
      "required": ["email"]
    }
  ]
}

유효한 데이터:

{
  "id": "user123",
  "name": "홍길동",
  "email": "hong@example.com"
}

사용 사례: 기본 사용자 정보와 연락처 정보를 결합할 때

anyOf: 하나 이상 충족 (OR)

anyOf는 최소 하나의 조건만 충족하면 됩니다. 여러 조건을 동시에 충족해도 됩니다.

{
  "type": "object",
  "properties": {
    "identifier": {
      "anyOf": [
        { "type": "string", "format": "email" },
        { "type": "string", "pattern": "^\\+[0-9]{1,3}-[0-9]{3,14}$" }
      ]
    }
  }
}

유효한 데이터:

{ "identifier": "test@example.com" }  // 이메일
{ "identifier": "+82-10-1234-5678" }  // 전화번호

무효한 데이터:

{ "identifier": "abc" }  // 이메일도 전화번호도 아님

사용 사례: 이메일 또는 전화번호로 로그인 가능한 경우

oneOf: 정확히 하나만 충족 (XOR)

oneOf는 정확히 하나의 스키마만 충족해야 합니다. 배타적 선택을 강제합니다.

{
  "type": "object",
  "properties": {
    "paymentMethod": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": { "const": "credit_card" },
            "cardNumber": { "type": "string" },
            "expiryDate": { "type": "string" }
          },
          "required": ["type", "cardNumber", "expiryDate"]
        },
        {
          "type": "object",
          "properties": {
            "type": { "const": "bank_transfer" },
            "accountNumber": { "type": "string" },
            "bankCode": { "type": "string" }
          },
          "required": ["type", "accountNumber", "bankCode"]
        },
        {
          "type": "object",
          "properties": {
            "type": { "const": "digital_wallet" },
            "walletId": { "type": "string" }
          },
          "required": ["type", "walletId"]
        }
      ]
    }
  }
}

사용 사례: 결제 방식 선택 (신용카드, 계좌이체, 디지털 지갑 중 하나만)

Apidog에서 구현하기

방법 1: 비주얼 에디터

1. Schemas 메뉴 클릭
2. Schema Composition 선택
3. 원하는 조합 방식(allOf/anyOf/oneOf) 선택
4. 각 하위 스키마 정의

방법 2: JSON Schema 코드 에디터

개발자에게 익숙한 JSON Schema를 직접 작성할 수 있습니다.

실무 적용 예제

검색 API 필터

{
  "oneOf": [
    {
      "properties": {
        "filterType": { "const": "date_range" },
        "startDate": { "type": "string", "format": "date" },
        "endDate": { "type": "string", "format": "date" }
      }
    },
    {
      "properties": {
        "filterType": { "const": "keyword" },
        "keyword": { "type": "string", "minLength": 2 }
      }
    },
    {
      "properties": {
        "filterType": { "const": "category" },
        "categoryIds": { "type": "array", "items": { "type": "string" } }
      }
    }
  ]
}

핵심 정리

비즈니스 로직에 맞는 조합 방식을 선택하면 API 문서의 모호함을 제거하고 API 사용자에게 명확한 가이드를 제공할 수 있습니다.