Lorsque votre API accepte plusieurs formats de données, comporte des champs conditionnels ou utilise des modèles d’héritage, les mots-clés de composition de schémas d’OpenAPI vous aident à documenter ces structures flexibles. Avec oneOf, anyOf et allOf, vous pouvez décrire des API qui gèrent différents types d’entrée ou combinent plusieurs schémas en modèles de données complets.

​
Mots-clés oneOf, anyOf, allOf

Pour les types de données complexes, OpenAPI propose des mots-clés pour combiner des schémas :
  • allOf : Combine plusieurs schémas (comme fusionner des objets ou étendre un schéma de base). Fonctionne comme un opérateur « and ».
  • anyOf : Accepte des données correspondant à l’un des schémas fournis. Fonctionne comme un opérateur « or ».
  • oneOf : Accepte des données correspondant à exactement un seul des schémas fournis. Fonctionne comme un opérateur « exclusive-or ».
Mintlify traite oneOf et anyOf de la même manière, car la différence pratique impacte rarement l’utilisation de l’API.
Pour des spécifications détaillées de ces mots-clés, consultez la documentation OpenAPI.
Le mot-clé not n’est actuellement pas pris en charge.

​
Combiner des schémas avec allOf

Lorsque vous utilisez allOf, Mintlify applique un prétraitement à votre document OpenAPI pour présenter des combinaisons complexes de manière lisible. Par exemple, lorsque vous combinez deux schémas d’objet avec allOf, Mintlify fusionne leurs propriétés en un seul objet. Cela est particulièrement utile lorsque vous exploitez les components réutilisables d’OpenAPI. 
org_with_users:
  allOf:
    - $ref: '#/components/schemas/Org'
    - type: object
      properties:
        users:
          type: array
          description: An array containing all users in the organization
# ...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: The ID of the organization
​
org_with_users
object

​
Proposer des options avec oneOf et anyOf

Lorsque vous utilisez oneOf ou anyOf, les options s’affichent dans un conteneur à onglets. Indiquez un champ title dans chaque sous-schéma pour nommer vos options. Par exemple, voici comment afficher deux types d’adresses de livraison : 
delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: The street address of the recipient
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: The number of the PO Box
        # ...
​
delivery_address
object
​
address_line_1
string
L’adresse de rue du domicile