Lors de la conception ou de la documentation d'une API avec la spécification OpenAPI (OAS), vous rencontrerez souvent le besoin de décrire des structures de données complexes. Ces structures peuvent nécessiter la définition de divers scénarios, tels que différentes structures d'objets pour différentes conditions, une combinaison de plusieurs objets en un seul, ou la spécification qu'un objet peut correspondre à l'un des nombreux types. C'est ici queoneOf,allOf, etanyOf briller, offrant la flexibilité et la précision nécessaires à ces tâches.

CompréhensionallOf

allOf est utilisé pour combiner plusieurs schémas en un seul schéma qui inclut toutes les propriétés des schémas combinés. C'est particulièrement utile lorsque vous souhaitez créer un schéma complexe qui hérite des propriétés de plusieurs autres schémas.

Par exemple, si vous avez unPerson schéma avec des propriétés communes commename etage, et unStudent schéma qui doit inclure toutes les propriétés dePerson plus a studentId, vous pouvez utiliserallOf pour créer leStudent schéma sans répéter lePerson propriétés.

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
    Student:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
          properties:
            studentId:
              type: string

ExplorantoneOf

oneOf spécifie que les données doivent correspondre exactement à l'un des schémas référencés. C'est utile pour définir différentes structures possibles pour un objet de données, où une seule structure est valide pour une instance donnée.

Prenons l'exemple d'un point de terminaison d'API qui accepte un mode de paiement, qui peut être une carte de crédit ou un compte bancaire, mais pas les deux. En utilisantoneOf, vous pouvez définir clairement ces options :

components:
  schemas:
    CreditCard:
      type: object
      properties:
        number:
          type: string
        expiryDate:
          type: string
        cvv:
          type: string
    BankAccount:
      type: object
      properties:
        accountNumber:
          type: string
        routingNumber:
          type: string
    PaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CreditCard'
        - $ref: '#/components/schemas/BankAccount'

DécryptageanyOf

anyOf permet aux données de correspondre à l'un (un ou plusieurs) des schémas référencés. Il offre de la flexibilité lorsque les données peuvent se présenter sous plusieurs formes, et il n'y a pas besoin d'exclusivité comme aveconeOf.

Par exemple, si un point de terminaison d'API accepte uncontact objet qui pourrait être soit unphone number, unemail address, ou les deux, vous pouvez utiliseranyOf pour représenter ceci :

components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        phone:
          type: string
    EmailAddress:
      type: object
      properties:
        email:
          type: string
    Contact:
      anyOf:
        - $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/schemas/EmailAddress'

Conclusion

LeallOf,oneOf, etanyOf Les mots-clés ajoutent une polyvalence essentielle aux spécifications OpenAPI, permettant la définition de modèles de données complexes et nuancés. En comprenant et en utilisant efficacement ces outils, les concepteurs et documenteurs d'API peuvent créer des spécifications d'API plus précises et plus flexibles. Que vous héritiez de propriétés, spécifiiez des types exclusifs ou autorisons plusieurs structures, ces mots-clés garantissent que les contrats de données de votre API sont clairs et robustes.