OpenAPI dokumentieren: Tags, Examples, Schemas und Responses sinnvoll aufbauen

1. Was gute API-Dokumentation leisten muss

Gute API-Dokumentation erfüllt drei Funktionen gleichzeitig: Sie erklärt warum ein Endpoint existiert und wann er verwendet wird, sie zeigt wie er konkret aufgerufen wird mit realistischen Beispieldaten, und sie definiert was im Fehlerfall zurückkommt. Dokumentation, die nur das technische Schema abbildet, beantwortet nur die dritte Frage. Teams, die ausschließlich den Code dokumentieren ohne Kontext und Beispiele, erzeugen Dokumentation die niemand liest – und damit Support-Anfragen, die Entwicklungszeit kosten.

Die häufigsten Beschwerden von Frontend-Teams über Backend-APIs: Fehlende Beispieldaten, unklare Fehlercodes, keine Erklärung wann welcher Status zurückkommt, und Schemas ohne Beschreibungen. All diese Probleme sind in OpenAPI lösbar – mit Tags für Struktur, Examples für konkrete Daten, Schema-Descriptions für Kontext und standardisierten Error-Responses. Der entscheidende Punkt: Diese Informationen gehören direkt in die OpenAPI-Spezifikation, nicht in eine separate Confluence-Seite, die nach dem ersten Release nicht mehr gepflegt wird.

OpenAPI-Dokumentation sollte als Single Source of Truth betrachtet werden. Mock-Server generieren aus der Spec realistische Testdaten, Code-Generatoren erstellen Client-SDKs, Contract-Tests validieren die Implementation gegen die Spec. Je vollständiger und präziser die Dokumentation, desto mehr Automatisierung ist ohne manuelle Nacharbeit möglich. Der Aufwand für gute Examples und Descriptions zahlt sich in weniger Support, schnellerer Frontend-Integration und zuverlässigerem Tooling zurück.

2. Tags: Gruppenstruktur und Navigation

Tags sind das Organisationssystem von OpenAPI. Jede Operation kann einem oder mehreren Tags zugeordnet werden – in Swagger UI und Redoc erscheinen sie dann als aufklappbare Gruppen. Tags ohne Root-Level-Definition erscheinen zwar in der Dokumentation, haben aber keinen Beschreibungstext und keine externe Dokumentationslinks. Das ist der häufige Fehler: Tags werden in Operationen zugewiesen, aber nie auf Root-Ebene mit Beschreibungen definiert.

Eine gute Tag-Struktur folgt den fachlichen Domänen der API, nicht den technischen Modulen. orders, products, customers und auth sind bessere Tags als OrderController oder v1_endpoints. Tags sollten Singular oder Plural konsistent verwenden – und alle Operationen eines Tags sollten eine zusammenhängende Ressource beschreiben. Operationen mit mehreren Tags erscheinen in mehreren Gruppen, was manchmal sinnvoll ist (z.B. ein Endpoint der sowohl zu orders als auch zu payments gehört), aber sparsam eingesetzt werden sollte.

# Tags auf Root-Ebene vollständig definieren — OpenAPI 3.1 Best Practice
tags:
  - name: orders
    description: |
      Bestellungen anlegen, abfragen und verwalten.

      ## Lifecycle
      `pending` → `confirmed` → `shipped` → `delivered`

      Stornierungen sind nur im Status `pending` oder `confirmed` möglich.
      Stornierte Bestellungen haben Status `cancelled` und können nicht reaktiviert werden.
    externalDocs:
      description: Bestellungs-Lifecycle Dokumentation
      url: https://docs.mironsoft.de/guides/order-lifecycle

  - name: products
    description: |
      Produktkatalog lesen und Lagerbestand abfragen.
      Produktdaten sind schreibgeschützt über diese API — Änderungen
      erfolgen im Admin-Backend.
    externalDocs:
      description: Produktdaten-Modell
      url: https://docs.mironsoft.de/guides/product-model

  - name: auth
    description: |
      Authentifizierung und Token-Management.

      Verwende `POST /auth/token` für initiale Authentifizierung.
      Tokens haben eine Gültigkeit von 1 Stunde.
      `POST /auth/token/refresh` verlängert ohne erneute Credentials.

  - name: webhooks
    description: |
      Webhook-Konfiguration für asynchrone Event-Benachrichtigungen.
      Unterstützte Events: order.created, order.status_changed, payment.received

3. Examples: Daten die wirklich nützlich sind

Examples in OpenAPI sind mehr als Platzhalter-Daten. Sie sind der direkte Kommunikationskanal zwischen Backend-Entwicklern und allen API-Konsumenten. Gute Examples sind realistisch (keine foo/bar-Werte), vollständig (alle relevanten Felder befüllt), kommentiert (über die summary und description Felder) und abdeckend (mehrere Szenarien pro Endpoint). Die examples-Sektion in requestBody und responses erlaubt mehrere benannte Examples, was für verschiedene Use-Cases besonders wertvoll ist.

Das Schlüsselprinzip: Examples sollen in components/examples zentralisiert werden und per $ref referenziert werden. So kann dasselbe Example in mehreren Operationen verwendet werden – zum Beispiel ein Bestell-Objekt das sowohl im POST-Response als auch im GET-Response erscheint. Examples in components/examples haben zusätzlich die Möglichkeit, ein externalValue-Feld zu nutzen, das auf eine externe JSON-Datei verweist. Das erlaubt sehr lange Beispieldaten ohne die YAML-Datei unlesbar zu machen.

# Examples in components — wiederverwendbar und beschrieben
components:
  examples:
    StandardOrder:
      summary: Normale Bestellung mit zwei Produkten
      description: |
        Typisches Beispiel einer Bestellung im Status 'confirmed'.
        Zeigt die vollständige Struktur mit allen Pflichtfeldern.
      value:
        id: "550e8400-e29b-41d4-a716-446655440000"
        status: confirmed
        items:
          - productId: "prod-001"
            productName: "Mironsoft Developer License"
            quantity: 1
            unitPrice: { amount: 199.00, currency: "EUR" }
          - productId: "prod-002"
            productName: "API Documentation Package"
            quantity: 2
            unitPrice: { amount: 49.00, currency: "EUR" }
        total: { amount: 297.00, currency: "EUR" }
        shippingAddress:
          street: "Hauptstraße 1"
          city: "Berlin"
          postalCode: "10115"
          country: "DE"
        createdAt: "2026-05-10T14:30:00Z"
        updatedAt: "2026-05-10T14:35:00Z"

    CreateOrderRequest:
      summary: Neue Bestellung anlegen
      description: Minimalbeispiel für das Anlegen einer Bestellung
      value:
        items:
          - productId: "prod-001"
            quantity: 1
        shippingAddressId: "addr-123"
        note: "Bitte bis 14 Uhr liefern"

    ValidationErrorExample:
      summary: Validierungsfehler bei fehlenden Pflichtfeldern
      value:
        type: "https://mironsoft.de/errors/validation-failed"
        title: "Validation Failed"
        status: 400
        detail: "The request body contains validation errors"
        instance: "/orders"
        errors:
          - field: "items"
            message: "At least one item is required"
          - field: "items[0].quantity"
            message: "Quantity must be greater than 0"

4. Schemas: Beschreibungen und Constraints richtig setzen

Ein Schema ohne Beschreibungen ist eine Typdeklaration – kein Dokument. Jedes Property das nicht selbsterklärend ist, braucht ein description-Feld. Die Beschreibung erklärt das Was und das Warum: nicht "Datum der Erstellung" sondern "ISO 8601 Zeitstempel wann die Bestellung im System angelegt wurde – read-only, wird vom Server gesetzt". Constraints wie minimum, maximum, minLength, maxLength, pattern und enum sind keine optionale Dokumentation, sondern Teil der API-Spezifikation – sie steuern Mock-Server-Validierung und Client-seitige Formvalidierung in generierten SDKs.

Das example-Feld auf Schema-Ebene ist für einfache Werte gedacht (ein einzelner String, eine Zahl). Das examples-Feld in Operations erlaubt mehrere vollständige Datensätze. Das Schema sollte außerdem readOnly: true für server-generierte Felder (id, createdAt) und writeOnly: true für Felder setzen, die nur in Requests erscheinen (Passwort-Hashes, Tokens). Das beeinflusst, welche Felder Code-Generatoren in Request- vs. Response-Klassen inkludieren.

5. Responses: Erfolg und Fehler standardisieren

Jede Operation sollte alle möglichen HTTP-Statuscodes dokumentieren, die sie zurückgeben kann – nicht nur 200. Mindestens: der Erfolgs-Response, 400 für Validierungsfehler, 401 für fehlende Authentifizierung, 403 für fehlende Autorisierung, 404 für nicht gefundene Ressourcen und 500 für Server-Fehler. Diese sechs Responses abzudecken ermöglicht es Client-Entwicklern, robuste Fehlerbehandlung zu implementieren ohne Überraschungen.

Alle Fehler-Responses sollten in components/responses zentralisiert sein. Statt in jeder Operation 404: {description: Not Found, content: {application/json: {schema: {…}}}}} zu wiederholen, wird einmal components/responses/NotFound definiert und in allen Operationen per $ref: '#/components/responses/NotFound' referenziert. Bei einer API mit 50 Endpoints und 5 Fehler-Typen spart das 200 Zeilen YAML und stellt sicher, dass alle Fehler-Responses dasselbe Schema verwenden.

# Standardisierte Responses in components — RFC 9457 Problem Details
components:
  responses:
    ValidationError:
      description: Validierungsfehler in Request-Daten
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            missing_field:
              $ref: '#/components/examples/ValidationErrorExample'

    Unauthorized:
      description: Authentifizierung fehlt oder Token ungültig
      headers:
        WWW-Authenticate:
          schema:
            type: string
          example: 'Bearer realm="mironsoft.de", error="invalid_token"'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: "https://mironsoft.de/errors/unauthorized"
            title: "Unauthorized"
            status: 401
            detail: "Bearer token is missing or has expired"

    NotFound:
      description: Ressource nicht gefunden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: "https://mironsoft.de/errors/not-found"
            title: "Not Found"
            status: 404
            detail: "The requested resource does not exist"

    InternalServerError:
      description: Interner Serverfehler
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'

6. RFC 9457 Problem Details als Fehler-Standard

RFC 9457 (früher RFC 7807) definiert ein standardisiertes Format für HTTP API-Fehlermeldungen: Problem Details for HTTP APIs. Das Schema hat fünf Standardfelder: type (URI die den Fehlertyp identifiziert), title (menschenlesbare Kurzbeschreibung), status (HTTP-Statuscode), detail (menschenlesbare Fehlerbeschreibung für diesen konkreten Request) und instance (URI die dieses konkrete Auftreten identifiziert). Alle Felder sind optional außer type, und eigene Erweiterungsfelder sind erlaubt.

Der Vorteil des Standards: Frontend-Teams und API-Konsumenten müssen nur ein Fehlerformat kennen, egal über welchen Endpoint ein Fehler zurückkommt. Der Content-Type für Problem Details ist application/problem+json (nicht application/json). Das erlaubt Middleware und Load-Balancern, Fehlerantworten korrekt zu erkennen. In OpenAPI wird application/problem+json als Media-Type in Fehler-Responses angegeben, was auch automatisch in generierten Clients berücksichtigt wird.

7. x-Extensions für tooling-spezifische Metadaten

OpenAPI erlaubt eigene Erweiterungsfelder mit dem Prefix x-. Diese werden von Standard-Parsern ignoriert, aber von spezifischen Tools ausgewertet. Häufig genutzte Extensions: x-codegen-request-body-name für Code-Generatoren, x-logo für Redoc für ein Logo in der Dokumentation, x-tagGroups für Redoc für eine zweistufige Tag-Hierarchie, x-internal um interne Endpoints aus der öffentlichen Dokumentation auszublenden, und eigene Extensions wie x-rate-limit für Rate-Limiting-Informationen pro Endpoint.

Custom Extensions sind ein mächtiges Werkzeug, sollten aber sparsam eingesetzt werden. Jede Extension ist implizit eine Dokumentationsschuld: Die Bedeutung muss irgendwo erklärt werden, und wenn das Tool sie nicht auswertet, hinterlässt sie ungenutzte Felder in der Spec. Eine sinnvolle Konvention: Extensions die nur für interne Build-Prozesse relevant sind, werden in einem eigenen Namespace gruppiert, z.B. x-mironsoft-deprecated-by statt einfach x-deprecated-by.

8. Gute vs. schlechte Dokumentationspraktiken im Vergleich

Die Qualität einer OpenAPI-Dokumentation zeigt sich in der Integration-Erfahrung von Konsumenten. Schlechte Dokumentation erzeugt Support-Anfragen, gute Dokumentation verhindert sie. Die folgende Tabelle zeigt typische Anti-Patterns und die empfohlene Alternative.

9. Zusammenfassung

Gute OpenAPI-Dokumentation ist das Ergebnis von vier konsequent umgesetzten Praktiken. Tags mit vollständigen Root-Level-Definitionen und Beschreibungen strukturieren die Dokumentation für Konsumenten, nicht für den Generator. Examples in components/examples mit realistischen Daten und mehreren Szenarien pro Endpoint machen Integration ohne Rückfragen möglich. Schemas mit Descriptions, Constraints und readOnly/writeOnly-Markierungen liefern maschinenlesbare und menschenverständliche Spezifikationen gleichzeitig. Responses in components/responses standardisiert nach RFC 9457 Problem Details ermöglichen robuste und konsistente Fehlerbehandlung.

Der einfachste erste Schritt für Teams mit bestehenden OpenAPI-Spezifikationen: Alle inline Fehler-Responses in components/responses zentralisieren und RFC 9457 als Fehlerschema einführen. Das verbessert sofort die Konsistenz und reduziert die Spec-Größe ohne Änderungen an der tatsächlichen API.

10. FAQ: OpenAPI Tags, Examples, Schemas und Responses