Quando la tua API accetta formati di dato multipli, prevede campi condizionali o utilizza modelli di ereditarietà, le keyword di composizione degli schemi di OpenAPI aiutano a documentare queste strutture flessibili. Con oneOf, anyOf e allOf puoi descrivere API che gestiscono tipi di input diversi o combinano più schemi in modelli di dati completi.

​
Parole chiave oneOf, anyOf, allOf

Per i tipi di dati complessi, OpenAPI fornisce parole chiave per combinare gli schemi:
  • allOf: Combina più schemi (ad esempio unire oggetti o estendere uno schema di base). Funziona come un operatore logico and.
  • anyOf: Accetta dati che corrispondono a uno qualsiasi degli schemi forniti. Funziona come un operatore logico or.
  • oneOf: Accetta dati che corrispondono esattamente a uno degli schemi forniti. Funziona come un operatore logico exclusive-or.
Mintlify tratta oneOf e anyOf nello stesso modo, poiché la differenza pratica raramente incide sull’utilizzo dell’API.
Per le specifiche dettagliate di queste parole chiave, consulta la documentazione OpenAPI.
La parola chiave not al momento non è supportata.

​
Combinare gli schemi con allOf

Quando usi allOf, Mintlify esegue del preprocessing sul documento OpenAPI per visualizzare combinazioni complesse in modo leggibile. Ad esempio, quando combini due schemi di tipo object con allOf, Mintlify unisce le proprietà di entrambi in un unico oggetto. Questo è particolarmente utile quando si sfruttano i componenti riutilizzabili di OpenAPI. 
org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: Un array contenente tutti gli utenti dell'organizzazione
# ...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: L'ID dell'organizzazione
​
org_with_users
object

​
Fornire opzioni con oneOf e anyOf

Quando utilizzi oneOf o anyOf, le opzioni vengono visualizzate in un contenitore a schede. Specifica un campo title in ciascun sottoschema per assegnare un nome alle opzioni. Ad esempio, ecco come potresti mostrare due tipi di indirizzo di consegna: 
delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: L’indirizzo stradale del destinatario
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: Il numero della casella postale
        # ...
​
delivery_address
object
​
address_line_1
string
L’indirizzo stradale dell’abitazione