OpenAPI (Swagger) – API-Dokumentation und Versionierung 2026

Kurzfassung

OpenAPI (ehemals Swagger) ist ein Standard zur Beschreibung von REST-APIs in YAML/JSON. Aus einer Spec lassen sich Dokumentation (Swagger UI, Redoc), Clients in verschiedenen Sprachen und Server-Stubs erzeugen. Spec im Repo neben dem Code pflegen und als Vertrag zwischen Frontend und Backend behandeln. API-Versionierung (z. B. /v1/, /v2/) von Anfang an planen.

Für wen ist das

• Backend- und Frontend-Entwickler, die über eine API zusammenarbeiten
• API-Architekten und Product Owner
• Teams, die APIs für externe Kunden anbieten

Keyword (SEO)

openapi swagger, api dokumentation, api versionierung, rest api spezifikation

Wozu OpenAPI?

• Eine Spec – beschreibt Endpoints, Request/Response, Typen, Beispiele
• Lesbare Doku – Swagger UI, Redoc – für Team und Partner
• Code-Generierung – Clients (TypeScript, Python usw.) und Server-Stub aus einer Datei
• Tests – Tools (Postman, Dredd) können API gegen die Spec validieren
• Vertrag – Frontend und Backend einigen sich auf die Spec; Änderungen = bewusste Version

Grundstruktur der Spec

openapi: 3.0.3
info:
  title: Mein API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Benutzer auflisten
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        name:
          type: string

Dokumentation aus der Spec

• Swagger UI – interaktive Doku, Requests ausführbar (z. B. mit Auth)
• Redoc – übersichtliches, „buchartiges“ Layout
• Beides aus derselben OpenAPI-Datei generierbar (z. B. in CI oder beim Serverstart)

Code-Generierung

• openapi-generator (OpenAPI Generator) – Clients: TypeScript, Python, Java, Go… sowie Server-Stub
• Orval (für TypeScript/React) – erzeugt Typen und API-Aufrufe aus OpenAPI
• Frontend bleibt nach Spec-Refresh mit Typen und Endpoints synchron

API-Versionierung

• URL – z. B. /v1/users, /v2/users – klar, Caching und Proxy einfach
• Header – z. B. Accept: application/vnd.api.v1+json – sauberere URL, seltener
• Policy – bei URL-Versionierung festlegen, wann v1 deprecated ist und wann abgeschaltet wird; in Doku und Headern (z. B. Deprecation, Sunset) kommunizieren

Empfehlung: Version in der URL (/v1/) für öffentliches API; intern kann man flexibler sein.

Best Practices

• Spec als Quelle der Wahrheit – im Repo halten, bei API-Änderungen anpassen; CI kann prüfen, dass der Server die Spec erfüllt (z. B. Kontrakt-Tests)
• Semantic Versioning – z. B. 1.0.0 → 1.1.0 bei neuem Feld (rückwärtskompatibel), 2.0.0 bei Breaking Change
• Beschreibungen und Beispiele – description, example in Schemas erleichtern API-Konsumenten die Arbeit
• security-Abschnitt – erforderliche Header (Bearer, API-Key) beschreiben; Swagger UI kann sie für Tests setzen

Checkliste

• OpenAPI-Datei im Repo (YAML oder JSON)
• Dokumentation (Swagger UI / Redoc) für Team und Kunden verfügbar
• Client- (oder Typ-)Generierung im Build
• Versionierungsregeln (v1, v2) und Deprecation
• Kontrakt-Tests (optional) – Server-Antworten entsprechen der Spec

FAQ

Ersetzt OpenAPI „manuelle“ Dokumentation?

Muss nicht. OpenAPI beschreibt den Vertrag (Endpoints, Schemas). Zusätzliche Doku (z. B. „Token erhalten“, Geschäftsszenarien) kann in einem Wiki oder in den Beschreibungen der Spec stehen.

Und bei GraphQL?

OpenAPI gilt für REST. Bei GraphQL nutzt man das GraphQL-Schema und Tools wie GraphQL Playground, Apollo Studio. Die Idee „eine Spec = Doku + Generierung“ ist ähnlich.

Wie Code und Spec in Einklang halten?

Option 1: Stub aus OpenAPI generieren und erweitern. Option 2: Code von Hand schreiben und in CI Spec aus Code erzeugen (z. B. Annotations in Java, Dekoratoren in Python) und mit „goldener“ OpenAPI-Datei vergleichen. Option 3: Kontrakt-Tests – Request/Response aus Tests gegen die Spec validieren.

API-Dokumentation aufräumen oder OpenAPI einführen?

• Kontakt