OpenAPI 3.1 von Grund auf: Die wichtigsten Bausteine praktisch erklärt

1. OpenAPI 3.1 vs. 3.0 – was sich geändert hat

OpenAPI 3.1 wurde im Februar 2021 veröffentlicht und brachte die wichtigste Änderung seit Version 2.0: volle Kompatibilität mit JSON Schema 2020-12. In OpenAPI 3.0 war das Schema-Objekt eine angepasste Teilmenge von JSON Schema Draft 7 mit proprietären Erweiterungen wie nullable. Diese Abweichungen führten zu Tooling-Problemen und semantischen Widersprüchen. OpenAPI 3.1 ersetzt diese Teilmenge durch vollständige JSON Schema 2020-12 Kompatibilität: type kann jetzt ein Array sein (type: [string, null] statt nullable: true), $ref darf mit anderen Schlüsseln kombiniert werden, und alle JSON Schema Keywords sind valide.

Die zweite wichtige Änderung betrifft Webhooks: OpenAPI 3.1 hat ein neues Top-Level-Feld webhooks, das Callbacks dokumentiert die ein API-Anbieter an seine Konsumenten sendet. In 3.0 musste man Webhooks in callbacks innerhalb von Operations vergraben. Das neue Feld macht asynchrone Benachrichtigungen zu einem First-Class-Citizen der API-Spezifikation. Dritte wichtige Neuerung: info.license unterstützt jetzt ein identifier-Feld nach SPDX-Standard statt nur einer URL.

Für die Praxis bedeutet die Migration von 3.0 auf 3.1 hauptsächlich: alle nullable: true durch type: [string, null] oder oneOf: [{type: string}, {type: 'null'}] ersetzen, exclusiveMinimum/exclusiveMaximum anpassen (in 3.1 sind diese jetzt Zahlen statt Booleans, wie in JSON Schema 2020-12 definiert) und die openapi-Version auf 3.1.0 setzen. Tooling-Support für 3.1 ist seit 2023 breit verfügbar – Swagger UI, Redoc, Stoplight, und die meisten Code-Generatoren unterstützen 3.1 vollständig.

2. Info, Servers und das Root-Objekt

Jede OpenAPI 3.1 Spezifikation beginnt mit dem Root-Objekt, das die Version, Metadaten und die verfügbaren Server definiert. Das info-Objekt ist Pflicht und enthält mindestens title und version. Die version ist die API-Version, nicht die OpenAPI-Spezifikationsversion – ein häufiger Fehler bei Einsteigern. Das servers-Array definiert die Basis-URLs der API für verschiedene Umgebungen. Ohne servers nehmen Clients an, dass der Server relativ zum Speicherort der Spezifikation ist.

Das externalDocs-Feld ermöglicht, auf weiterführende Dokumentation zu verlinken. tags auf Root-Ebene definieren Gruppen mit Beschreibungen, die dann in Operations referenziert werden – das ist wichtig für eine saubere Dokumentationsstruktur. Das info.contact-Objekt mit Name, E-Mail und URL ist für öffentliche APIs unverzichtbar. Das info.termsOfService-Feld verlinkt die Nutzungsbedingungen. All diese Felder sind für automatisch generierte Dokumentationsseiten und Developer Portals relevante Metadaten.

# openapi.yaml — Root Object, vollständiges Beispiel OpenAPI 3.1
openapi: 3.1.0

info:
  title: Mironsoft Commerce API
  version: "2.0.0"
  description: |
    REST API für den Mironsoft Commerce-Stack.
    Unterstützte Authentifizierung: Bearer JWT, OAuth 2.0 (Authorization Code).
  contact:
    name: Mironsoft API Support
    email: api@mironsoft.de
    url: https://mironsoft.de/support
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary

servers:
  - url: https://api.mironsoft.de/v2
    description: Production
  - url: https://api-staging.mironsoft.de/v2
    description: Staging
  - url: http://localhost:8080/v2
    description: Local Development

tags:
  - name: orders
    description: Bestellungen anlegen, lesen und verwalten
    externalDocs:
      description: Order-Lifecycle Dokumentation
      url: https://docs.mironsoft.de/orders
  - name: products
    description: Produktkatalog und Lagerbestand
  - name: auth
    description: Authentifizierung und Token-Management

externalDocs:
  description: Vollständige Mironsoft Developer Docs
  url: https://docs.mironsoft.de

3. Paths und Operations: der Kern der API

Das paths-Objekt ist das Herzstück jeder OpenAPI-Spezifikation. Jeder Schlüssel ist ein URL-Pfad-Template, jeder Wert ein Path Item Object das die HTTP-Methoden und deren Operationen definiert. Eine Operation hat mindestens ein responses-Objekt, sollte aber auch operationId, summary, description und tags enthalten. Die operationId ist besonders wichtig: Code-Generatoren verwenden sie als Funktionsname, daher muss sie eindeutig, sprechend und konventionskonform sein – z.B. getOrderById, createOrder, updateOrderStatus.

Pfad-Templates nutzen geschweifte Klammern für Pfad-Parameter: /orders/{orderId}. Jeder in geschweiften Klammern definierte Parameter muss im parameters-Array der Operation (oder des Path Items) mit in: path deklariert werden. Path-Parameter sind immer required: true – das schreibt die Spezifikation vor. Auf Path-Item-Ebene definierte Parameter gelten für alle Operationen des Pfades und können in einzelnen Operationen überschrieben werden. Dieses Muster eignet sich für Auth-Parameter die für alle Methoden eines Endpoints gelten.

# Paths und Operations — vollständiges Beispiel für /orders/{orderId}
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Neue Bestellung anlegen
      tags: [orders]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              standard_order:
                $ref: '#/components/examples/StandardOrder'
      responses:
        '201':
          description: Bestellung erfolgreich angelegt
          headers:
            Location:
              description: URL der neuen Ressource
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /orders/{orderId}:
    parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Eindeutige ID der Bestellung (UUID v4)

    get:
      operationId: getOrderById
      summary: Bestellung abrufen
      tags: [orders]
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Bestellung gefunden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'

4. Parameters: Path, Query, Header und Cookie

OpenAPI unterscheidet vier Arten von Parametern anhand des in-Feldes: path, query, header und cookie. Path-Parameter sind Bestandteile des URL-Pfades und immer required. Query-Parameter erscheinen nach dem ? und sind typischerweise optional für Filterung, Sortierung und Paginierung. Header-Parameter dokumentieren benutzerdefinierte HTTP-Header (Standard-Header wie Authorization werden über security definiert). Cookie-Parameter dokumentieren Werte, die über Cookies übertragen werden.

Jeder Parameter hat ein schema-Objekt, das den Datentyp und Validierungsregeln definiert. Für Query-Parameter mit komplexen Datenstrukturen ist das style-Feld wichtig: form (Standard), spaceDelimited, pipeDelimited oder deepObject steuern, wie Arrays und Objekte serialisiert werden. Das Feld explode: true (Standard für form) erzeugt separate Parameter pro Array-Element (?tag=a&tag=b), explode: false kombiniert sie (?tag=a,b). Diese Details sind entscheidend für die Kompatibilität mit automatisch generiertem Client-Code.

5. Schemas mit JSON Schema 2020-12

In OpenAPI 3.1 sind Schemas vollständige JSON Schema 2020-12 Objekte. Das bedeutet voller Zugriff auf alle JSON Schema Keywords: type als Array, if/then/else für bedingte Validierung, $defs für lokale Definitionen, unevaluatedProperties für strenge Schemas und prefixItems für typisierte Tuple-Arrays. Die wichtigste praktische Änderung gegenüber OpenAPI 3.0: nullable: true existiert nicht mehr. Stattdessen wird type: [string, "null"] oder ein oneOf mit einem Null-Type verwendet.

Gut designte Schemas nutzen description, example (oder examples), default, minimum/maximum, minLength/maxLength, pattern und enum wo sinnvoll. Diese Felder sind nicht nur für Dokumentation wichtig – sie steuern die Validierung in Mock-Servern, die Codegenerierung in Client-SDKs und die Validierungslogik in serverseitigen Middleware-Layern. Ein Schema ohne Beschreibungen und Beispiele ist technisch korrekt, aber für Konsumenten weitgehend nutzlos.

# Schemas mit JSON Schema 2020-12 — OpenAPI 3.1 Beispiel
components:
  schemas:
    Order:
      type: object
      required: [id, status, items, total, createdAt]
      description: Vollständige Bestellrepräsentation
      properties:
        id:
          type: string
          format: uuid
          description: Eindeutige Bestellungs-ID
          examples: ["550e8400-e29b-41d4-a716-446655440000"]
          readOnly: true
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered, cancelled]
          description: Aktueller Status der Bestellung
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        total:
          type: object
          required: [amount, currency]
          properties:
            amount:
              type: number
              format: decimal
              minimum: 0
              exclusiveMinimum: true
              description: Gesamtbetrag in der angegebenen Währung
            currency:
              type: string
              pattern: '^[A-Z]{3}$'
              description: ISO 4217 Währungscode
              examples: ["EUR", "USD"]
        note:
          type: ["string", "null"]
          maxLength: 500
          description: Optionale Bestellnotiz (null wenn nicht gesetzt)
        createdAt:
          type: string
          format: date-time
          readOnly: true
      additionalProperties: false

6. Components: Wiederverwendung ohne Duplikate

Das components-Objekt ist das Bibliotheks-System von OpenAPI. Es enthält wiederverwendbare Definitionen, auf die mit $ref verwiesen werden kann. Verfügbare Sektionen: schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks und – neu in 3.1 – pathItems. Die konsequente Nutzung von components ist der wichtigste Faktor für eine wartbare OpenAPI-Spezifikation. Wer Schemas inline in Operationen definiert, erzeugt Duplikate die bei Änderungen an vielen Stellen angepasst werden müssen.

Für gemeinsame Fehlerresponses lohnt sich ein standardisiertes Error-Schema. Eine RFC 9457 Problem Details-kompatible Fehlerstruktur mit type, title, status, detail und instance ist in components/schemas definiert und wird von allen Fehler-Responses in components/responses referenziert. So haben alle 4xx- und 5xx-Antworten automatisch ein einheitliches Format, das in einer einzigen Änderung aktualisiert werden kann.

7. Security Schemes: Bearer, OAuth2 und API-Key

OpenAPI 3.1 unterstützt vier Security-Scheme-Typen: http (für Basic und Bearer), apiKey, oauth2 und openIdConnect. Security-Schemes werden in components/securitySchemes definiert und können dann auf Root-Ebene als Standard oder auf Operations-Ebene gezielt angewendet werden. Ein leeres Array security: [] in einer Operation überschreibt die globale Security und markiert den Endpoint als öffentlich zugänglich.

OAuth 2.0 in OpenAPI ist besonders komplex: Das oauth2-Schema enthält für jeden Flow (authorizationCode, clientCredentials, implicit, password) separate Konfigurationen mit Authorization-URL, Token-URL und Scope-Definitionen. Scopes werden in der Operation im Security-Array als String-Array angegeben. Die Scope-Definitionen müssen vollständig und sprechend sein – Swagger UI generiert daraus die OAuth-Consent-UI in der interaktiven Dokumentation.

# Security Schemes — Bearer JWT + OAuth 2.0 in OpenAPI 3.1
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT Bearer Token. Abrufen via POST /auth/token.
        Header: Authorization: Bearer <token>

    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.mironsoft.de/oauth/authorize
          tokenUrl: https://auth.mironsoft.de/oauth/token
          refreshUrl: https://auth.mironsoft.de/oauth/token/refresh
          scopes:
            orders:read: Bestellungen lesen
            orders:write: Bestellungen erstellen und aktualisieren
            products:read: Produktkatalog lesen
            admin: Administrativer Zugriff auf alle Ressourcen

    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API-Key für Server-zu-Server Kommunikation

# Global security — gilt für alle Operationen
security:
  - BearerAuth: []

# Öffentlicher Endpoint — überschreibt globale Security
paths:
  /products:
    get:
      operationId: listProducts
      security: []  # Public endpoint, no auth required
      summary: Produkte öffentlich abrufen
      tags: [products]
      responses:
        '200':
          description: Produktliste

8. OpenAPI 3.0 vs. 3.1 im direkten Vergleich

Der Wechsel von OpenAPI 3.0 auf 3.1 ist für die meisten APIs keine Breaking Change auf API-Ebene, erfordert aber Anpassungen in der Spezifikationsdatei. Die folgende Tabelle zeigt die wichtigsten Unterschiede und Migrationsschritte für Teams, die eine bestehende 3.0 Spezifikation aktualisieren wollen.

9. Zusammenfassung

OpenAPI 3.1 ist ein vollständig durchdachter Standard, der alle Aspekte einer REST API beschreiben kann – von einfachen CRUD-Endpoints bis zu komplexen OAuth-Flows und asynchronen Webhooks. Die wichtigsten Bausteine: Das Root-Objekt mit Info und Servers, das Paths-Objekt mit Operationen und operationId, das Parameters-System mit den vier Typen, JSON Schema 2020-12 für Schemas, Components für Wiederverwendung und Security Schemes für Authentifizierung. Wer alle diese Bausteine konsequent einsetzt, erhält eine Spezifikation, die Codegenerierung, Mock-Server, Validierung und interaktive Dokumentation ohne Nacharbeit unterstützt.

Der größte Hebel für neue Teams: Die operationId konsequent und sprechend benennen, alle Fehlerresponses in components/responses zentralisieren und Schemas immer in components/schemas definieren – niemals inline. Diese drei Entscheidungen verhindern die häufigsten Wartungsprobleme und machen die Spezifikation für Code-Generatoren optimal nutzbar.

10. FAQ: OpenAPI 3.1 Bausteine