Quando si progetta o si documenta un'API con la specifica OpenAPI (OAS), incontrerai spesso la necessità di descrivere strutture di dati complesse. Queste strutture potrebbero richiedere la definizione di vari scenari, come diverse strutture di oggetti per condizioni diverse, una combinazione di più oggetti in uno solo o specificando che un oggetto potrebbe corrispondere a uno qualsiasi dei diversi tipi. Qui è doveoneOf,allOf, EanyOf brillare, offrendo la flessibilità e la precisione necessarie per questi compiti.

ComprensioneallOf

allOf viene utilizzato per combinare più schemi in un unico schema che include tutte le proprietà degli schemi combinati. È particolarmente utile quando si desidera creare uno schema complesso che erediti proprietà da diversi altri schemi.

Ad esempio, se hai aPerson schema con proprietà comuni comename Eage, e aStudent schema che dovrebbe includere tutte le proprietà diPerson più distudentId, Puoi usareallOf per creare ilStudent schema senza ripetere ilPerson proprietà.

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

EsplorandooneOf

oneOf specifica che i dati devono corrispondere esattamente a uno degli schemi di riferimento. È utile per definire diverse strutture possibili per un oggetto dati, dove solo una struttura è valida per ogni data istanza.

Considera un endpoint API che accetta un metodo di pagamento, che potrebbe essere una carta di credito o un conto bancario, ma non entrambi. UtilizzandooneOf, puoi definire chiaramente queste opzioni:

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'

DecifrareanyOf

anyOf consente ai dati di corrispondere a uno qualsiasi (uno o più) degli schemi di riferimento. Fornisce flessibilità quando i dati possono essere in diverse forme e non è necessaria l'esclusività come nel casooneOf.

Ad esempio, se un endpoint API accetta acontact oggetto che potrebbe essere aphone number, UNemail address, o entrambi, è possibile utilizzareanyOf per rappresentare questo:

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'

Conclusione

ILallOf,oneOf, EanyOf Le parole chiave aggiungono versatilità essenziale alle specifiche OpenAPI, consentendo la definizione di modelli di dati complessi e ricchi di sfumature. Comprendendo e utilizzando questi strumenti in modo efficace, i progettisti e i documentatori API possono creare specifiche API più precise e flessibili. Che tu erediti proprietà, specifichi tipi esclusivi o consenta più strutture, queste parole chiave garantiscono che i contratti dati della tua API siano chiari e solidi.