Tipos de datos complejos

Describe APIs con esquemas flexibles, propiedades opcionales y múltiples formatos de datos usando los keywords oneOf, anyOf y allOf

Cuando tu API acepta varios formatos de datos, tiene campos condicionales o utiliza patrones de herencia, los keywords de composición de esquemas de OpenAPI te ayudan a documentar estas estructuras flexibles. Con oneOf, anyOf y allOf, puedes describir APIs que procesan distintos tipos de entrada o combinan varios esquemas en modelos de datos completos.

​

Palabras clave oneOf, anyOf, allOf

Para tipos de datos complejos, OpenAPI proporciona palabras clave para combinar esquemas:

• allOf: Combina varios esquemas (como fusionar objetos o extender un esquema base). Opera como un operador and.
• anyOf: Acepta datos que coincidan con cualquiera de los esquemas proporcionados. Opera como un operador or.
• oneOf: Acepta datos que coincidan exactamente con uno de los esquemas proporcionados. Opera como un operador exclusive-or.

Mintlify trata oneOf y anyOf de manera idéntica, ya que la diferencia práctica rara vez afecta el uso de la API.

Para consultar las especificaciones detalladas de estas palabras clave, revisa la documentación de OpenAPI.

La palabra clave not no es compatible actualmente.

​

Combinación de esquemas con allOf

Cuando usas allOf, Mintlify realiza cierto preprocesamiento en tu documento de OpenAPI para mostrar combinaciones complejas de manera legible. Por ejemplo, cuando combinas dos esquemas de objeto con allOf, Mintlify unifica las propiedades de ambos en un solo objeto. Esto resulta especialmente útil al aprovechar los components reutilizables de OpenAPI.

org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: Una matriz que contiene todos los usuarios de la organización
# ...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: El ID de la organización

org_with_users · object

Mostrar atributos secundarios

id · string

El ID de la organización

users · object[]

Un arreglo que contiene a todos los usuarios de la organización

​

Proporcionar opciones con oneOf y anyOf

Cuando usas oneOf o anyOf, las opciones se muestran en un contenedor con pestañas. Especifica un campo title en cada subesquema para asignar nombres a tus opciones. Por ejemplo, así podrías mostrar dos tipos diferentes de direcciones de entrega:

delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: La dirección postal del destinatario
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: El número del apartado postal
        # ...

delivery_address · object

StreetAddress

address_line_1 · string

La dirección de la vivienda

POBox

box_number · string

El número del apartado postal