Types de données complexes

Décrivez des API avec des schémas flexibles, des propriétés optionnelles et plusieurs formats de données à l’aide des mots-clés oneOf, anyOf et allOf

Lorsque votre API accepte plusieurs formats de données, comporte des champs conditionnels ou utilise des schémas 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 prennent en charge 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 fournit des mots-clés pour combiner des schémas :

• allOf : combine plusieurs schémas (comme la fusion d’objets ou l’extension d’un schéma de base). Fonctionne comme un opérateur « and ».
• anyOf : accepte des données correspondant à l’un quelconque 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 manière identique, car la différence pratique influe rarement sur 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 effectue un prétraitement de votre document OpenAPI afin d’afficher des combinaisons complexes de manière lisible. Par exemple, lorsque vous combinez deux schémas d’objet avec allOf, Mintlify regroupe les propriétés des deux en un seul objet. Cela devient 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: Un tableau contenant tous les utilisateurs de l'organisation
# ...
components:
  schemas:
    Org:
      type: object
      properties:
        id:
          type: string
          description: L'identifiant de l'organisation

org_with_users · object

Show child attributes

id · string

L’identifiant de l’organisation

users · object[]

Un tableau contenant tous les utilisateurs de l’organisation

​

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 différents :

delivery_address:
  oneOf:
    - title: StreetAddress
      type: object
      properties:
        address_line_1:
          type: string
          description: L'adresse postale du destinataire
        # ...
    - title: POBox
      type: object
      properties:
        box_number:
          type: string
          description: Le numéro de la boîte postale
        # ...

delivery_address · object

StreetAddress

address_line_1 · string

L’adresse de la rue du domicile