OAS(OpenAPI 사양)를 사용하여 API를 설계하거나 문서화할 때 복잡한 데이터 구조를 설명해야 하는 경우가 종종 있습니다. 이러한 구조에는 다양한 조건에 대한 다양한 개체 구조, 여러 개체를 하나로 결합하거나 개체가 여러 유형 중 하나와 일치할 수 있도록 지정하는 등 다양한 시나리오의 정의가 필요할 수 있습니다. 이곳은oneOf,allOf, 그리고anyOf 이러한 작업에 필요한 유연성과 정확성을 제공합니다.

이해allOf

allOf 여러 스키마를 결합된 스키마의 모든 속성을 포함하는 단일 스키마로 결합하는 데 사용됩니다. 여러 다른 스키마에서 속성을 상속하는 복잡한 스키마를 생성하려는 경우 특히 유용합니다.

예를 들어,Person 다음과 같은 공통 속성을 가진 스키마name 그리고age, 그리고Student 모든 속성을 포함해야 하는 스키마Person 이상studentId, 당신이 사용할 수있는allOf 만들기 위해Student 반복하지 않고 스키마Person 속성.

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
    Student:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
          properties:
            studentId:
              type: string

탐색oneOf

oneOf 데이터가 참조된 스키마 중 하나와 정확히 일치해야 함을 지정합니다. 이는 특정 인스턴스에 대해 하나의 구조만 유효한 데이터 개체에 대해 가능한 다양한 구조를 정의하는 데 유용합니다.

신용 카드나 은행 계좌 중 하나일 수 있지만 둘 다를 허용하지 않는 결제 방법을 허용하는 API 엔드포인트를 생각해 보세요. 사용oneOf, 다음 옵션을 명확하게 정의할 수 있습니다.

components:
  schemas:
    CreditCard:
      type: object
      properties:
        number:
          type: string
        expiryDate:
          type: string
        cvv:
          type: string
    BankAccount:
      type: object
      properties:
        accountNumber:
          type: string
        routingNumber:
          type: string
    PaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CreditCard'
        - $ref: '#/components/schemas/BankAccount'

해독anyOf

anyOf 데이터가 참조된 스키마 중 하나 이상과 일치하도록 허용합니다. 데이터가 여러 형식일 수 있는 경우 유연성을 제공하며 다음과 같은 독점성이 필요하지 않습니다.oneOf.

예를 들어, API 엔드포인트가contact 다음 중 하나일 수 있는 객체phone number,email address또는 둘 다 사용할 수 있습니다.anyOf 이것을 표현하기 위해:

components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        phone:
          type: string
    EmailAddress:
      type: object
      properties:
        email:
          type: string
    Contact:
      anyOf:
        - $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/schemas/EmailAddress'

결론

그만큼allOf,oneOf, 그리고anyOf 키워드는 OpenAPI 사양에 필수적인 다양성을 추가하여 복잡하고 미묘한 데이터 모델을 정의할 수 있게 해줍니다. API 디자이너와 문서 작성자는 이러한 도구를 효과적으로 이해하고 사용함으로써 보다 정확하고 유연한 API 사양을 만들 수 있습니다. 속성을 상속하든, 배타적 유형을 지정하든, 여러 구조를 허용하든 이러한 키워드는 API의 데이터 계약이 명확하고 강력하도록 보장합니다.