Al diseñar o documentar una API con la especificación OpenAPI (OAS), a menudo encontrará la necesidad de describir estructuras de datos complejas. Estas estructuras pueden requerir la definición de varios escenarios, como diferentes estructuras de objetos para diferentes condiciones, una combinación de varios objetos en uno o especificar que un objeto podría coincidir con cualquiera de varios tipos. Aquí es dondeoneOf,allOf, yanyOf brillan, ofreciendo la flexibilidad y precisión necesarias para estas tareas.

ComprensiónallOf

allOf se utiliza para combinar varios esquemas en un solo esquema que incluye todas las propiedades de los esquemas combinados. Es particularmente útil cuando desea crear un esquema complejo que herede propiedades de varios otros esquemas.

Por ejemplo, si tienes unPerson esquema con propiedades comunes comoname yage, y unStudent esquema que debe incluir todas las propiedades dePerson más questudentId, puedes usarallOf para crear elStudent esquema sin repetir elPerson propiedades.

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

ExploradoroneOf

oneOf especifica que los datos deben coincidir exactamente con uno de los esquemas a los que se hace referencia. Es útil para definir diferentes estructuras posibles para un objeto de datos, donde solo una estructura es válida para una instancia determinada.

Considere un punto final API que acepte un método de pago, que podría ser una tarjeta de crédito o una cuenta bancaria, pero no ambas. UsandooneOf, puedes definir estas opciones claramente:

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'

DescifrandoanyOf

anyOf permite que los datos coincidan con cualquiera (uno o más) de los esquemas referenciados. Proporciona flexibilidad cuando los datos pueden estar en varias formas y no hay necesidad de exclusividad como ocurre cononeOf.

Por ejemplo, si un punto final API acepta uncontact objeto que podría ser unphone number, unemail address, o ambos, puedes usaranyOf para representar esto:

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'

Conclusión

ElallOf,oneOf, yanyOf Las palabras clave añaden una versatilidad esencial a las especificaciones de OpenAPI, permitiendo la definición de modelos de datos complejos y matizados. Al comprender y utilizar estas herramientas de manera efectiva, los diseñadores y documentadores de API pueden crear especificaciones de API más precisas y flexibles. Ya sea que esté heredando propiedades, especificando tipos exclusivos o permitiendo múltiples estructuras, estas palabras clave garantizan que los contratos de datos de su API sean claros y sólidos.