OpenAPI 3.2 vs 3.1 vs 3.0: Die Neuerungen im Vergleich

TL;DR

OpenAPI 3.1 fügte volle JSON-Schema-Kompatibilität, Webhooks und Verbesserungen am Diskriminator hinzu. OpenAPI 3.2 fügte Unterstützung für die QUERY-Methode, verbesserte Beispiele und bessere Sicherheitsdefinitionen hinzu. Das moderne PetstoreAPI verwendet OpenAPI 3.2, um alle neuesten Funktionen mit produktionsreifen Beispielen zu demonstrieren.

Einleitung

Sie schreiben eine OpenAPI-Spezifikation. Sie sehen Verweise auf OpenAPI 3.0, 3.1 und 3.2. Was ist der Unterschied? Sollten Sie ein Upgrade durchführen? Werden Ihre Tools die neue Version unterstützen?

OpenAPI hat sich von 3.0 auf 3.2 erheblich weiterentwickelt. Jede Version fügt Funktionen hinzu, die API-Spezifikationen leistungsfähiger und präziser machen. Doch nicht alle Tools unterstützen die neuesten Versionen, was eine Kompatibilitätsproblematik schafft.

Das alte Swagger Petstore verwendet OpenAPI 2.0 (Swagger-Spezifikation). Modern PetstoreAPI verwendet OpenAPI 3.2 und demonstriert jede neue Funktion mit produktionsreifen Beispielen.

💡

Wenn Sie REST-APIs entwickeln oder testen, unterstützt Apidog OpenAPI 3.0, 3.1 und 3.2. Sie können Spezifikationen importieren, gegen das Schema validieren und Ihre API-Implementierung testen. Apidog hilft Ihnen zu verstehen, welche Version Sie verwenden sollten und wie Sie migrieren können.

button

In diesem Leitfaden erfahren Sie, was sich in jeder OpenAPI-Version geändert hat, wie Sie die richtige Version auswählen und wie Modern PetstoreAPI die Funktionen von OpenAPI 3.2 demonstriert.

OpenAPI 3.0 als Basis

OpenAPI 3.0 (veröffentlicht im Juli 2017) war ein großes Upgrade von Swagger 2.0.

Hauptfunktionen

1. Mehrere Server

servers:
  - url: https://api.petstoreapi.com/v1
    description: Production
  - url: https://staging.petstoreapi.com/v1
    description: Staging

Swagger 2.0 unterstützte nur einen Host.

2. Request-Body-Objekt

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'

Klarer als der body-Parameter von Swagger 2.0.

3. Komponenten für Wiederverwendbarkeit

components:
  schemas:
    Pet:
      type: object
  responses:
    NotFound:
      description: Resource not found
  parameters:
    PetId:
      name: petId
      in: path

Bessere Organisation als die definitions von Swagger 2.0.

4. Callbacks

Definieren Sie asynchrone Callbacks (Webhooks):

callbacks:
  orderUpdate:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderUpdate'

5. Links

Definieren Sie Beziehungen zwischen Operationen:

links:
  GetPetByPetId:
    operationId: getPetById
    parameters:
      petId: '$response.body#/id'

Einschränkungen

1. JSON-Schema-Inkompatibilität

OpenAPI 3.0 verwendete eine Untermenge von JSON Schema Draft 5, nicht das vollständige JSON Schema. Dies führte zu Validierungsproblemen.

2. Kein Webhooks-Objekt

Webhooks wurden als Callbacks definiert, was verwirrend war.

3. Begrenzter Diskriminator

Die Unterstützung für Polymorphie war grundlegend.

4. Kein Null-Typ

Sie konnten type: null nicht direkt angeben.

OpenAPI 3.1 Wichtige Änderungen

OpenAPI 3.1 (veröffentlicht im Februar 2021) konzentrierte sich auf die Angleichung an das JSON-Schema.

1. Volle JSON-Schema 2020-12 Kompatibilität

Die größte Änderung: OpenAPI 3.1 Schemas sind gültige JSON Schema 2020-12.

Vorher (OpenAPI 3.0):

type: string
nullable: true  # OpenAPI-specific

Nachher (OpenAPI 3.1):

type: [string, "null"]  # Standard JSON Schema

Vorteile:

Jeden JSON-Schema-Validator verwenden
Schemas zwischen OpenAPI und anderen Tools teilen
Zugriff auf alle JSON-Schema-Funktionen

2. Webhooks-Objekt

Vorher (OpenAPI 3.0):

# Webhooks defined as callbacks (confusing)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # webhook definition

Nachher (OpenAPI 3.1):

webhooks:
  orderUpdate:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'

Klarere Trennung zwischen API-Endpunkten und Webhooks.

3. Verbesserter Diskriminator

Bessere Unterstützung für Polymorphie:

oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
discriminator:
  propertyName: petType
  mapping:
    cat: '#/components/schemas/Cat'
    dog: '#/components/schemas/Dog'

4. Lizenz-ID im Info-Objekt

info:
  license:
    name: MIT
    identifier: MIT  # SPDX identifier

5. PathItem $ref

Referenzieren Sie ganze Path-Items:

paths:
  /pets:
    $ref: '#/components/pathItems/PetsCollection'

Abwärtsinkompatible Änderungen

1. nullable entfernt

Verwenden Sie stattdessen type: [string, "null"].

2. exclusiveMinimum/exclusiveMaximum geändert

Jetzt boolesch, nicht numerisch.

3. example vs examples

Strengere Validierung.

OpenAPI 3.2 Neueste Funktionen

OpenAPI 3.2 (Veröffentlichung noch festzulegen, Entwurf verfügbar) fügt moderne API-Muster hinzu.

1. Unterstützung der QUERY-Methode

HTTP-QUERY-Methode für komplexe Suchen:

paths:
  /pets/search:
    query:  # New method
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: Search results

Modern PetstoreAPI verwendet QUERY für komplexe Haustiersuchen.

2. Verbesserte Beispiele

Mehrere Beispiele mit Metadaten:

examples:
  availableCat:
    summary: Available cat
    description: A cat available for adoption
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: Adopted dog
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. Erweiterte Sicherheitsdefinitionen

Bessere OAuth 2.0 Unterstützung:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://petstoreapi.com/oauth/authorize
          tokenUrl: https://petstoreapi.com/oauth/token
          refreshUrl: https://petstoreapi.com/oauth/refresh
          scopes:
            pets:read: Read pets
            pets:write: Create and update pets
            orders:read: Read orders

4. Verbesserte Diskriminator-Zuordnung

Flexiblere Polymorphie:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Can mix local and $ref

5. Bessere Unterstützung für Veralterung

Spezifische Felder als veraltet markieren:

properties:
  oldField:
    type: string
    deprecated: true
    description: Use newField instead
  newField:
    type: string

Wie Modern PetstoreAPI OpenAPI 3.2 verwendet

Modern PetstoreAPI demonstriert jede Funktion von OpenAPI 3.2.

1. Vollständige Spezifikation

Die vollständige OpenAPI 3.2 Spezifikation ist verfügbar unter:

https://petstoreapi.com/openapi.json

2. QUERY-Methode für komplexe Suchen

/pets/search:
  query:
    summary: Search pets with complex criteria
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. Webhooks

webhooks:
  petStatusChanged:
    post:
      summary: Pet status changed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. Polymorphe Schemas

Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Bird'
  discriminator:
    propertyName: species

5. Umfassende Beispiele

Jeder Endpunkt enthält mehrere Beispiele, die verschiedene Szenarien zeigen.

6. RFC 9457 Fehlerantworten

responses:
  '400':
    description: Bad Request
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

Die vollständige OpenAPI-Spezifikation für alle Funktionen finden Sie hier.

Migrationsleitfaden

3.0 zu 3.1

1. Ersetzen Sie nullable:

# Before
type: string
nullable: true

# After
type: [string, "null"]

2. Aktualisieren Sie exclusiveMinimum/exclusiveMaximum:

# Before
minimum: 0
exclusiveMinimum: true

# After
minimum: 0
exclusiveMinimum: 0

3. Verschieben Sie Webhooks:

# Before
paths:
  /subscribe:
    callbacks:
      # webhook

# After
webhooks:
  # webhook

3.1 zu 3.2

1. Fügen Sie bei Bedarf QUERY-Methoden hinzu:

/pets/search:
  query:  # New in 3.2
    # complex search

2. Verbessern Sie Beispiele:

examples:
  example1:
    summary: Description
    value: {...}

3. Aktualisieren Sie Sicherheitsdefinitionen:

Fügen Sie refreshUrl zu OAuth-Flows hinzu.

Testen von OpenAPI-Spezifikationen mit Apidog

Apidog unterstützt alle OpenAPI-Versionen.

OpenAPI-Spezifikation importieren

1. Apidog öffnen
2. Auf "Importieren" klicken
3. "OpenAPI 3.x" auswählen
4. URL einfügen oder Datei hochladen
5. Apidog validiert und importiert

Spezifikation validieren

Apidog prüft:

Schema-Gültigkeit
Referenzintegrität
Korrektheit der Beispiele
Vollständigkeit der Sicherheitsdefinitionen

API-Implementierung testen

Generieren Sie Testfälle aus der Spezifikation:

Anfragevalidierung
Antwortvalidierung
Statuscode-Prüfungen
Schema-Konformität

Versionsvergleich

Importieren und vergleichen Sie mehrere Versionen:

Abwärtsinkompatible Änderungen
Neue Endpunkte
Schema-Änderungen
Veraltete Felder

Fazit

OpenAPI hat sich erheblich weiterentwickelt:

OpenAPI 3.0: Grundlage mit Servern, Request-Bodies, Callbacks

OpenAPI 3.1: JSON-Schema-Kompatibilität, Webhooks-Objekt, bessere Polymorphie

OpenAPI 3.2: QUERY-Methode, erweiterte Beispiele, verbesserte Sicherheit

Modern PetstoreAPI verwendet OpenAPI 3.2, um alle Funktionen mit produktionsreifen Beispielen zu demonstrieren. Es ist die Referenzimplementierung für modernes API-Design.

Verwenden Sie Apidog, um mit jeder OpenAPI-Version zu arbeiten, Spezifikationen zu validieren und Implementierungen zu testen.

FAQ

Sollte ich auf OpenAPI 3.1 oder 3.2 upgraden?

Wenn Ihre Tools dies unterstützen, ja. Die JSON-Schema-Kompatibilität von OpenAPI 3.1 ist wertvoll. OpenAPI 3.2 fügt moderne Muster wie die QUERY-Methode hinzu.

Funktioniert meine OpenAPI 3.0 Spezifikation mit 3.1 Tools?

Meistens, aber nullable und exclusiveMinimum/exclusiveMaximum benötigen Updates.

Unterstützen Codegeneratoren OpenAPI 3.2?

Die Unterstützung wächst. Überprüfen Sie die Dokumentation Ihres Generators. Viele unterstützen 3.1, weniger 3.2.

Kann ich OpenAPI 3.2 Funktionen in 3.1 verwenden?

Nein. Verwenden Sie die Version, die zu Ihren Funktionen passt. Wenn Sie die QUERY-Methode benötigen, verwenden Sie 3.2.

Wie validiere ich meine OpenAPI-Spezifikation?

Verwenden Sie Apidog, um Ihre Spezifikation zu importieren und zu validieren. Es überprüft die Schema-Gültigkeit und Referenzintegrität.

Wo finde ich ein vollständiges OpenAPI 3.2 Beispiel?

Modern PetstoreAPI bietet eine vollständige, produktionsreife OpenAPI 3.2 Spezifikation.

Was ist der Unterschied zwischen Webhooks und Callbacks?

Webhooks sind HTTP-Anfragen vom Server an den Client. Callbacks sind in OpenAPI 3.0 als Teil von Operationen definiert. OpenAPI 3.1+ hat ein dediziertes webhooks-Objekt.

Sollte ich JSON oder YAML für OpenAPI-Spezifikationen verwenden?

Beide funktionieren. YAML ist für Menschen lesbarer. JSON ist für Tools einfacher. Modern PetstoreAPI bietet beide Formate.