OpenAPI und Swagger: APIs dokumentieren und testen

Kurz: OpenAPI beschreibt eine REST-Schnittstelle maschinenlesbar in YAML oder JSON; daraus entstehen Dokumentation, Testwerkzeuge und sogar fertiger Client-Code.

Genauer: Wer eine API anbietet, muss sagen, welche Endpunkte es gibt, welche Parameter sie erwarten und was sie zurückgeben. Die OpenAPI-Spezifikation (früher Swagger) legt dafür ein Standardformat fest. Werkzeuge wie Swagger UI, Redoc und Postman lesen es.

Im Detail

Beispiel

openapi: 3.0.3
info:
  title: Aufgaben-API
  version: 1.0.0
paths:
  /aufgaben:
    get:
      summary: Alle Aufgaben holen
      responses:
        '200':
          description: Liste
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Aufgabe' }
components:
  schemas:
    Aufgabe:
      type: object
      required: [id, titel]
      properties:
        id: { type: integer }
        titel: { type: string }
        erledigt: { type: boolean }

Nutzen

• Interaktive Dokumentation: In Swagger UI kann man Anfragen direkt ausprobieren.
• Code-Generierung: Client-Bibliotheken und Server-Gerüste in vielen Sprachen.
• Validierung von Anfragen und Antworten.
• Mock-Server für Frontend-Entwicklung vor dem Backend.
• Verträge: Frontend und Backend einigen sich auf eine Spezifikation (Contract First).
• Tests, die prüfen, ob die API der Beschreibung entspricht.

Zwei Wege

Contract First: Erst die Spezifikation schreiben, dann implementieren. Code First: Aus Annotationen oder Typen im Code wird die Spezifikation erzeugt (zum Beispiel FastAPI, Spring, NestJS). Wichtig ist, dass Beschreibung und Code nicht auseinanderlaufen: Prüfe im Build, ob die Spezifikation aktuell ist.

Gute Praxis

Beschreibe Fehlerantworten (400, 401, 404, 500) und deren Format, gib Beispiele an, nutze wiederverwendbare Schemas, dokumentiere Authentifizierung (Bearer, API-Key, OAuth) und Versionierung. Veröffentliche keine internen Endpunkte oder Beispieldaten mit echten personenbezogenen Daten.

Siehe auch: REST-API-Design, API-Versionierung, Dateiformate (YAML, JSON u. a.), README-Datei