API-Mocking aus OpenAPI-Spezifikationen erzeugen

1. Warum API-Mocking aus Specs – nicht aus Fixtures

Der klassische Ansatz für API-Mocking ist eine Sammlung statischer JSON-Dateien, die das Frontend während der Entwicklung einliest. Das funktioniert für einfache Szenarien, aber es hat einen systematischen Nachteil: Die Fixtures divergieren von der echten API. Wenn Backend ein Feld umbenennt, einen Status-Code ändert oder ein neues Pflichtfeld hinzufügt, bleiben die Fixture-Dateien unverändert. Das Frontend entwickelt gegen veraltete Daten und merkt das erst bei der Integration.

Mock-Server, die direkt aus der OpenAPI-Spezifikation arbeiten, lösen dieses Problem fundamental. Die Spezifikation ist die Single Source of Truth – und jede Änderung daran wirkt sich sofort auf den Mock-Server aus. Das Frontend-Team bekommt automatisch aktualisierte Antworten, ohne die Fixtures manuell pflegen zu müssen. Außerdem kann ein spec-basierter Mock-Server Request-Daten gegen das Request-Schema validieren und bei Verstößen einen Fehler zurückgeben – das deckt Frontend-Bugs auf, bevor das Backend überhaupt fertig ist.

2. Prism: Mock-Server direkt aus OpenAPI starten

Prism von Stoplight ist das meistgenutzte Tool für spec-basiertes API-Mocking. Es liest eine OpenAPI-Datei und startet innerhalb von Sekunden einen HTTP-Server, der alle darin definierten Endpoints beantwortet. Die Antworten werden aus den im Spec definierten examples-Feldern zusammengestellt. Das bedeutet: Wer sorgfältig Beispiele in der Spezifikation pflegt, bekommt einen Mock-Server, dessen Antworten exakt dem Vertrag entsprechen.

Prism unterstützt mehrere Betriebsmodi. Im Standard-Modus gibt es das erste definierte Beispiel zurück. Mit dem Header Prefer: example=active_user kann ein Frontend-Entwickler ein spezifisches Beispiel anfordern – und so verschiedene Zustände testen, die in der Spec definiert sind. Der --errors-Modus aktiviert Request-Validierung: Jeder Request, der dem Schema nicht entspricht, wird mit einem 422-Fehler abgelehnt, statt durchgelassen zu werden. Das ist besonders wertvoll für Frontend-Entwickler, die sicherstellen wollen, dass ihre Request-Körper der Spec entsprechen.

# Install Prism globally
npm install -g @stoplight/prism-cli

# Start mock server from OpenAPI spec (static examples mode)
prism mock api/openapi.yaml --port 4010

# With request validation active (rejects invalid requests with 422)
prism mock api/openapi.yaml --port 4010 --errors

# Dynamic mode: generate fake data when no example is defined
prism mock api/openapi.yaml --port 4010 --dynamic

# Proxy mode: forward to real API, validate request/response against spec
prism proxy api/openapi.yaml http://api.example.com --port 4011 --errors

# Test specific example with Prefer header
curl -H "Prefer: example=active_user" http://localhost:4010/users/42

# Test 404 response
curl http://localhost:4010/users/99999
# Returns 404 with example from spec

# Run in Docker for CI (no global npm install needed)
docker run --rm -p 4010:4010 \
  -v "$(pwd)/api/openapi.yaml:/tmp/spec.yaml" \
  stoplight/prism:4 mock /tmp/spec.yaml --host 0.0.0.0

3. Prism im Dynamic-Modus: Fake-Daten aus dem Schema

Im statischen Beispiel-Modus von Prism gibt es immer dieselben Antworten zurück – nützlich für deterministische Tests, aber begrenzt für die Entwicklung von Listen und Paginierung. Der Dynamic-Modus von Prism generiert zufällige, aber schema-konforme Daten für jede Anfrage. Ein string-Feld bekommt einen zufälligen String, ein integer-Feld eine Zufallszahl, ein enum-Feld einen der definierten Werte. format-Hints wie email, date-time und uuid werden dabei respektiert.

Das Ergebnis ist ein Mock-Server, der für jede Anfrage realistische Daten liefert – ausreichend, um Layouts mit echten Datenlängen zu testen und Listenkomponenten mit verschiedenen Datensätzen zu entwickeln. Für komplexere Szenarien – wie zustandsbehaftete Simulationen oder abhängige Daten zwischen Endpoints – ist WireMock die bessere Wahl. Für reine Schema-Konformität und schnelles Bootstrapping ist Prism unübertroffen.

4. WireMock: Erweiterte Mocks mit Zustand und Sequenzen

WireMock ist ein vollständiger HTTP-Stub-Server mit einer mächtigen Konfigurationssprache für komplexe Szenarien. Im Gegensatz zu Prism, das rein spec-basiert arbeitet, ermöglicht WireMock zustandsbehaftete Mocks: Ein erster POST /orders erzeugt eine Bestellung, ein anschließendes GET /orders/1 gibt sie zurück – vollständig konsistent. Sequenz-Szenarien simulieren APIs, die bei wiederholten Anfragen verschiedene Zustände zurückgeben: der erste GET /status gibt pending zurück, der zweite processing, der dritte completed.

WireMock kann aus OpenAPI-Spezifikationen initialisiert werden, aber die eigentliche Stärke liegt in den manuell definierten Stub-Mappings. Diese Mappings können während der Laufzeit über die Admin-API dynamisch hinzugefügt und entfernt werden – besonders nützlich für Test-Setups, die verschiedene Szenarien zwischen Tests schalten müssen. WireMock ist für Integrationstests und komplexe QA-Szenarien die bessere Wahl als Prism, erfordert aber mehr Konfigurationsaufwand.

{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "urlPattern": "/users/[0-9]+"
      },
      "response": {
        "status": 200,
        "headers": { "Content-Type": "application/json" },
        "jsonBody": {
          "id": 42,
          "email": "user@example.com",
          "name": "Maria Mustermann",
          "role": "editor",
          "active": true,
          "createdAt": "2025-01-15T10:30:00Z"
        }
      }
    },
    {
      "scenarioName": "Order-Status-Flow",
      "requiredScenarioState": "Started",
      "request": { "method": "GET", "url": "/orders/1/status" },
      "response": { "status": 200, "jsonBody": { "status": "pending" } },
      "newScenarioState": "Processing"
    },
    {
      "scenarioName": "Order-Status-Flow",
      "requiredScenarioState": "Processing",
      "request": { "method": "GET", "url": "/orders/1/status" },
      "response": { "status": 200, "jsonBody": { "status": "completed" } }
    }
  ]
}

5. MSW: Mocking direkt im Browser und Node.js

Mock Service Worker (MSW) verfolgt einen anderen Ansatz als Prism und WireMock: Es interceptiert HTTP-Requests direkt im Browser über einen Service Worker, ohne einen separaten Server zu starten. Das bedeutet, dass Mock-Handlers in JavaScript geschrieben werden und direkt in das Frontend-Projekt integriert sind. Für React-, Vue- oder Svelte-Anwendungen ist MSW oft die natürlichere Integration als ein externer Mock-Server.

Mit der openapi-fetch-Bibliothek und MSW-Handlers aus der OpenAPI-Spec können vollständig typsichere Mocks erzeugt werden. In der Testumgebung (Jest, Vitest) laufen dieselben Handlers im Node.js-Modus ohne Browser. Der entscheidende Vorteil von MSW: Mock-Handlers und echte API-Calls nutzen denselben Code-Pfad – das macht es einfacher, zwischen gemocktem und echtem Backend zu wechseln, ohne Testcode grundlegend umzuschreiben.

# Install MSW in a frontend project
npm install msw --save-dev

# Initialize Service Worker for browser mode
npx msw init public/ --save

# Generate MSW handlers from OpenAPI spec
npx openapi-msw generate \
  --input api/openapi.yaml \
  --output src/mocks/handlers.ts \
  --typescript

# src/mocks/browser.ts — MSW browser setup
# import { setupWorker } from 'msw/browser'
# import { handlers } from './handlers'
# export const worker = setupWorker(...handlers)

# Start frontend dev server with mocks active
VITE_API_MOCKING=enabled npm run dev

# Run unit tests with MSW in Node mode (Jest/Vitest)
npm test -- --testPathPattern=api

# Generate TypeScript types from OpenAPI spec (keeps types in sync with mock)
npx openapi-typescript api/openapi.yaml -o src/api/schema.d.ts

6. Fehlerszenarien gezielt simulieren

Ein Mock-Server, der nur Erfolgsantworten zurückgibt, testet nur die Happy-Path-Pfade des Frontends. Fehlerszenarien sind mindestens genauso wichtig: Was passiert, wenn die API 500 zurückgibt? Wie behandelt das Frontend einen 401-Fehler mit abgelaufenem Token? Was zeigt die UI bei einem 429-Rate-Limit? Diese Szenarien müssen gezielt simulierbar sein.

Prism ermöglicht Fehler-Simulationen über den Prefer-Header: Prefer: code=500 erzwingt einen 500-Fehler, unabhängig davon, welcher Endpoint angesprochen wird. WireMock kann Timeouts ("fixedDelayMilliseconds": 30000), Netzwerkfehler ("fault": "CONNECTION_RESET_BY_PEER") und fehlerhafte Responses ("fault": "MALFORMED_RESPONSE_CHUNK") simulieren – Szenarien, die in manuellen Tests kaum reproduzierbar sind. MSW-Handlers können jeden Error-Response direkt in JavaScript kodieren und zwischen Tests schalten.

7. Mock-Server in CI-Pipelines integrieren

Mock-Server in CI-Pipelines zu integrieren ist entscheidend für isolierte, reproduzierbare Tests ohne externe Abhängigkeiten. Das Muster: Mock-Server startet im Hintergrund, Test-Suite läuft dagegen, Mock-Server wird beendet. Mit Docker sind Mock-Server in CI ohne Installationsaufwand verfügbar. Die Herausforderung liegt im Timing: Der Test darf erst starten, wenn der Mock-Server bereit ist – ein wait-on-Check auf den Health-Endpoint löst das zuverlässig.

Ein weiterer CI-Anwendungsfall: Prism im --proxy-Modus vor dem echten API-Server betreiben und Request/Response-Validierung aktivieren. Jeder Contract-Verstoß – auch wenn Backend und Frontend funktionieren – wird als Fehler gemeldet. Das erkennt Abweichungen zwischen Implementierung und Spezifikation, die ohne Validierungsschicht unsichtbar wären. Dieser Ansatz ist besonders wertvoll in Teams, die Code-First arbeiten und die Spec nachträglich generieren.

# .github/workflows/api-tests.yml — Prism mock server in CI
name: API Contract Tests

on: [push, pull_request]

jobs:
  contract-tests:
    runs-on: ubuntu-latest
    services:
      prism:
        image: stoplight/prism:4
        ports:
          - 4010:4010
        options: >-
          --health-cmd "wget -q --spider http://localhost:4010/health || exit 1"
          --health-interval 5s
          --health-timeout 3s
          --health-retries 10

    steps:
      - uses: actions/checkout@v4

      - name: Copy spec to service
        run: docker cp api/openapi.yaml prism:/tmp/spec.yaml

      - name: Setup Node
        uses: actions/setup-node@v4
        with: { node-version: '20' }

      - run: npm ci

      - name: Wait for mock server
        run: npx wait-on http://localhost:4010/health --timeout 30000

      - name: Run contract tests against mock
        run: npm test -- --testPathPattern=contract
        env:
          API_BASE_URL: http://localhost:4010
          NODE_ENV: test

8. Prism vs. WireMock vs. MSW: Direktvergleich

Die drei Tools lösen dasselbe Grundproblem – API-Abhängigkeiten eliminieren – aber mit verschiedenen Schwerpunkten und Integrationsmodellen. Die Wahl hängt davon ab, in welchem Kontext der Mock-Server laufen soll und wie komplex die Szenarien sind.

In der Praxis ergänzen sich die Tools: Prism für schnelles Bootstrapping und spec-nahe Mocks in der Entwicklung und CI, WireMock für komplexe Integrationstests mit Zustandsmanagement, MSW für Unit-Tests und Komponenten-Tests direkt im Frontend-Projekt. Viele Teams nutzen alle drei – in verschiedenen Teilen der Test-Pyramide.

9. Zusammenfassung

API-Mocking aus OpenAPI-Spezifikationen ist die moderne Alternative zu manuell gepflegten Fixture-Dateien. Prism startet in Sekunden einen spec-konformen Mock-Server mit optionaler Request-Validierung und dynamischer Datengenerierung. WireMock ermöglicht zustandsbehaftete Szenarien, Netzwerkfehler-Simulation und komplexe Sequenzen für Integrationstests. MSW integriert Mocking direkt in das Frontend-Projekt und ermöglicht typsichere Handlers aus der OpenAPI-Spec.

Der gemeinsame Nenner: Alle drei Tools eliminieren die manuelle Pflege von Mock-Daten und halten Mocks automatisch synchron mit der Spezifikation. Das bedeutet weniger Zeit für Mock-Wartung, mehr Vertrauen in die Tests und eine Frontend-Entwicklung, die nicht auf Backend-Fertigstellung warten muss.

10. FAQ: API-Mocking aus OpenAPI-Spezifikationen