Saltar al contenido principal
Cuando tu API acepta varios formatos de datos, tiene campos condicionales o utiliza patrones de herencia, las palabras clave de composición de esquemas de OpenAPI te ayudan a documentar estas estructuras flexibles. Con oneOf, anyOf y allOf, puedes describir APIs que admiten diferentes tipos de entrada o combinan múltiples 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). Funciona como un operador lógico and.
  • anyOf: Acepta datos que coincidan con cualquiera de los esquemas proporcionados. Funciona como un operador lógico or.
  • oneOf: Acepta datos que coincidan con exactamente uno de los esquemas proporcionados. Funciona como un operador xor (o “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 leer las especificaciones detalladas de estas palabras clave, consulta la documentación de OpenAPI.
La palabra clave not actualmente no es compatible.

​
Combinación de esquemas con allOf

Cuando usas allOf, Mintlify realiza cierto preprocesamiento en tu documento de OpenAPI para mostrar combinaciones complejas de forma legible. Por ejemplo, cuando combinas dos esquemas de objeto con allOf, Mintlify fusiona las propiedades de ambos en un solo objeto. Esto resulta especialmente útil al aprovechar los componentes reutilizables de OpenAPI. 
org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: Una lista que contiene a 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

​
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 nombre 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 del destinatario
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: El número del apartado de correos
        # ...
​
delivery_address
object
  • StreetAddress
  • POBox
​
address_line_1
string
La dirección de la residencia