Beim Entwerfen oder Dokumentieren einer API mit OpenAPI Specification (OAS) werden Sie häufig auf die Notwendigkeit stoßen, komplexe Datenstrukturen zu beschreiben. Diese Strukturen erfordern möglicherweise die Definition verschiedener Szenarios, z. B. unterschiedliche Objektstrukturen für unterschiedliche Bedingungen, eine Kombination mehrerer Objekte zu einem oder die Angabe, dass ein Objekt einem von mehreren Typen entsprechen könnte. Das ist wooneOf,allOf, UndanyOf glänzen und bieten die Flexibilität und Präzision, die für diese Aufgaben erforderlich sind.

VerständnisallOf

allOf wird verwendet, um mehrere Schemas zu einem einzigen Schema zu kombinieren, das alle Eigenschaften der kombinierten Schemas enthält. Dies ist besonders nützlich, wenn Sie ein komplexes Schema erstellen möchten, das Eigenschaften von mehreren anderen Schemas erbt.

Wenn Sie beispielsweise eine habenPerson Schema mit gemeinsamen Eigenschaften wiename Undage, und einStudent Schema, das alle Eigenschaften von enthalten solltePerson mehr alsstudentId, können Sie verwendenallOf zu erstellenStudent Schema, ohne das zu wiederholenPerson Eigenschaften.

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

ErkundenoneOf

oneOf Gibt an, dass die Daten genau mit einem der referenzierten Schemata übereinstimmen sollen. Dies ist nützlich, um verschiedene mögliche Strukturen für ein Datenobjekt zu definieren, wobei für jede Instanz nur eine Struktur gültig ist.

Stellen Sie sich einen API-Endpunkt vor, der eine Zahlungsmethode akzeptiert, bei der es sich entweder um eine Kreditkarte oder ein Bankkonto handeln kann, jedoch nicht um beides. BenutzenoneOfkönnen Sie diese Optionen klar definieren:

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'

EntschlüsselunganyOf

anyOf ermöglicht, dass die Daten mit einem oder mehreren der referenzierten Schemata übereinstimmen. Es bietet Flexibilität, wenn die Daten in verschiedenen Formen vorliegen können, und es besteht kein Bedarf an Exklusivität wie beioneOf.

Wenn beispielsweise ein API-Endpunkt a akzeptiertcontact Objekt, das entweder ein sein könntephone number, einemail addressoder beides können Sie verwendenanyOf um dies darzustellen:

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'

Abschluss

DerallOf,oneOf, UndanyOf Schlüsselwörter verleihen OpenAPI-Spezifikationen eine wesentliche Vielseitigkeit und ermöglichen die Definition komplexer und differenzierter Datenmodelle. Durch das Verständnis und den effektiven Einsatz dieser Tools können API-Designer und -Dokumentierer genauere und flexiblere API-Spezifikationen erstellen. Unabhängig davon, ob Sie Eigenschaften erben, exklusive Typen angeben oder mehrere Strukturen zulassen, stellen diese Schlüsselwörter sicher, dass die Datenverträge Ihrer API klar und robust sind.