OpenAPI

Was ist OpenAPI?

OpenAPI ist eine maschinenlesbare Beschreibung einer HTTP API. In einem einzigen Dokument, geschrieben in YAML oder JSON, werden jeder Endpunkt, seine Parameter, Request-Bodies, Responses und die Authentifizierung aufgelistet. Da diese Beschreibung strukturiert ist, kann sie von verschiedenen Tools genutzt werden: Dokumentations-UIs, typisierte Clients, Server-Stubs, Mocks und Validatoren.

Swagger war der ursprüngliche Name; heute bezieht sich dieser Begriff auf das Tooling, insbesondere auf Swagger UI. Die Spezifikation selbst heißt OpenAPI und hat sich zum De-facto-Standard für die Beschreibung von REST APIs entwickelt. Wenn Sie jemals eine interaktive API-Referenz mit einem „Try it out“-Button verwendet haben, haben Sie OpenAPI genutzt.

Der Aufbau eines Dokuments

Ein OpenAPI-Dokument besteht aus einigen Top-Level-Sektionen.

# openapi.yaml
openapi: 3.1.0
info:
  title: Posts API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /posts:
    get:
      summary: List posts
      responses:
        "200":
          description: A list of posts

• openapi legt die Version der Spezifikation fest.
• info enthält den Titel, die Version und die Beschreibung.
• servers listet die Basis-URLs auf.
• paths beschreibt jeden Endpunkt und die dazugehörigen Operationen.
• components enthält wiederverwendbare Elemente.

Pfade und Operationen

Jeder Pfad wird einer oder mehreren HTTP-Methoden zugeordnet, und jede Operation beschreibt deren Inputs und Outputs.

# paths.yaml
paths:
  /posts/{id}:
    get:
      summary: Get a post
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: The post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
        "404":
          description: Not found

Parameter können im path, query, header oder cookie definiert werden. Request-Bodies werden mit einem Content-Type und einem Schema deklariert, und jede Response sollte ihre Status-Codes und Strukturen auflisten. Gute Zusammenfassungen und Beschreibungen machen die Spezifikation bereits an sich zu einer nützlichen Dokumentation.

Komponenten und Referenzen

Wiederverwendbarkeit ist der Schlüssel zur Wartbarkeit einer Spezifikation. Definieren Sie Shapes einmalig und referenzieren Sie diese mit $ref.

# components.yaml
components:
  schemas:
    Post:
      type: object
      required: [id, title]
      properties:
        id: { type: string }
        title: { type: string }
        publishedAt: { type: string, format: date-time }
  parameters:
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 100 }
  responses:
    NotFound:
      description: Resource not found

Eine Änderung am Post-Schema aktualisiert jede Operation, die darauf verweist. So wird ein Auseinanderdriften verhindert, das oft bei duplizierten Definitionen auftritt.

Sicherheit

Die Authentifizierung wird einmal definiert und pro Operation zugewiesen.

# security.yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Tools können dann die entsprechenden Anmeldedaten in der Dokumentations-UI senden, und generierte Clients können einen Token-Parameter akzeptieren.

Dokumentation und Codegenerierung

Die Spec steuert das Tooling:

• Swagger UI rendert eine interaktive Referenz, in der Benutzer Requests ausprobieren können.
• Redoc rendert eine übersichtliche Dokumentationsseite mit drei Spalten.
• openapi-generator erstellt Clients und Server-Stubs in vielen verschiedenen Sprachen.
• openapi-typescript generiert TypeScript-Typen aus der Spec.
• Spectral führt ein Linting der Spec durch, um Konsistenz und Style zu gewährleisten.
• Mock-Server liefern Beispielantworten aus, sodass die Front-end-Entwicklung beginnen kann, noch bevor das Backend fertiggestellt ist.

# docs.sh
npx @redocly/cli preview-docs openapi.yaml
npx openapi-typescript openapi.yaml -o src/api-types.ts

Da alles aus einer einzigen Datei abgeleitet wird, bleiben die Dokumentation, die Clients und die Typen konsistent.

Spec-first gegenüber Code-first

Es gibt zwei Workflows:

• Spec-first: Der Contract wird entworfen, bevor die Implementierung erfolgt. Ideal für öffentliche APIs, mehrere Konsumenten sowie die parallele Entwicklung von Front-end und Back-end. Die Spec ist hierbei die „Source of Truth“.
• Code-first: Routen und Typen werden annotiert, woraus anschließend die Spec generiert wird. Dies hält die Spec nah an der Implementierung und vermeidet Duplikationen in typisierten Frameworks.

Beide Ansätze funktionieren. Die größte Fehlerquelle ist in beiden Fällen die manuelle Pflege der Dokumentation an einem separaten Ort, wodurch diese schleichend veraltet.

Validierung und Contract Testing

Ein OpenAPI-Dokument kann nicht nur gelesen, sondern auch erzwungen werden.

• Request-Validierung: Eine middleware lehnt Requests ab, die nicht der Spezifikation entsprechen, sodass Handler ihren Inputs vertrauen können.
• Response-Validierung: Tests stellen sicher, dass Responses den erklärten Schemas entsprechen.
• Contract Testing: Clients und Server prüfen beide gegen dieselbe Spezifikation, wodurch Breaking Changes frühzeitig erkannt werden.

Hier beweist die Spezifikation ihren Wert: Sie wird zu einem ausführbaren Vertrag anstatt zu bloßer Dekoration.

Best Practices

• Verwenden Sie pro API nur eine Spec und behandeln Sie diese als “Source of Truth”.
• Wiederverwenden Sie Schemas, Parameter und Responses mithilfe von $ref.
• Schreiben Sie klare Zusammenfassungen und Beschreibungen; diese bilden die Grundlage für die Dokumentation.
• Dokumentieren Sie jeden Statuscode, den eine Operation zurückgeben kann.
• Validieren Sie Requests und Responses gegen die Spec.
• Generieren Sie Clients, Types und Dokumentationen, anstatt diese manuell zu schreiben.
• Nutzen Sie einen Linter für die Spec und prüfen Sie Änderungen in Pull Requests.

Häufige Fehler

• Manuelle Pflege der Dokumentation getrennt von der Spec.
• Inline-Duplizierung von Schemas, bis diese voneinander abweichen.
• Fehlende Error-Responses, wodurch Clients Fehler nicht korrekt behandeln können.
• Verwendung vager Namen und Beschreibungen, die den Konsumenten nicht weiterhelfen.
• Zulassen einer Diskrepanz (Drift) zwischen der Spec und der Implementierung.
• Verzicht auf Validierung, wodurch der Hauptvorteil des Contracts verloren geht.

Wie geht es weiter?

OpenAPI macht eine API zu einem Vertrag, den sowohl Tools als auch Menschen nutzen können. Bauen Sie diese auf Basis eines soliden REST-Designs auf, entwickeln Sie sie sorgfältig mittels API-Versioning weiter und richten Sie sie am HTTP-Guide aus. Beschreiben Sie anschließend einen Endpunkt, den Sie bereits implementiert haben, und generieren Sie daraus einen Client.