OpenAPI Mock-Server für Frontend-Entwicklung aufsetzen

1. Das Problem: Frontend wartet auf Backend

In den meisten Projekten beginnt das Frontend erst zu arbeiten, wenn der erste echte API-Endpunkt bereitsteht. Das Backend-Team kämpft mit Datenbankmigrationen und Authentifizierungslogik, während das Frontend-Team mit statischen Dummy-Daten in Komponenten-Dateien arbeitet, die später wieder herausgelöst werden müssen. Dieses sequenzielle Muster verlängert die Lieferzeit, erzeugt unnötige Integrationsfehler beim ersten Zusammenschalten und führt zu einer Codebasis, in der Dummy-Daten-Reste für Verwirrung sorgen.

Der Ausweg liegt in einem OpenAPI Mock-Server, der aus der gemeinsam vereinbarten API-Spec automatisch realistische HTTP-Antworten generiert. Sobald Backend- und Frontend-Teams die Spec abgestimmt haben — Endpunkte, Request-Schemas, Response-Schemas — kann das Frontend-Team vollständig und unabhängig entwickeln, testen und sogar Fehlerszenarien durchspielen, ohne dass ein einziger Backend-Endpunkt live ist. Die Spec ist der Vertrag, der beide Teams synchronisiert.

Ein weiterer Vorteil: Mock-Server sind deterministisch. Produktionsdatenbanken mit realen Inhalten haben oft Edge Cases, die lokal schwer reproduzierbar sind. Ein Mock-Server liefert genau die Daten, die man für einen bestimmten Testfall braucht — Pagination am letzten Element, ein leeres Array, ein 503-Fehler nach drei Sekunden — ohne Datenbankmanipulation oder Testdaten-Cleanup.

2. Prism: Mock-Server aus OpenAPI-Spec in einer Zeile

Prism von Stoplight ist das verbreitetste Tool für OpenAPI-basierte Mock-Server. Es liest eine lokale oder remote OpenAPI-Datei und startet sofort einen HTTP-Server, der alle definierten Endpunkte simuliert. Prism generiert Antworten aus den in der Spec definierten examples — sind keine vorhanden, erzeugt es syntaktisch korrekte Zufallsdaten passend zum Schema. Ein JSON-Array von Produkten mit type: array und items: { type: object, properties: { id: integer, name: string } } liefert sofort eine Antwort wie [{"id": 42, "name": "mock-1337"}], ohne eine Zeile Code zu schreiben.

Prism unterstützt außerdem den --errors-Modus, in dem es eingehende Requests gegen die Spec validiert und bei Verstößen detaillierte Fehlermeldungen zurückgibt, statt blind zu antworten. Das ist besonders wertvoll in frühen Entwicklungsphasen, wo Frontend-Entwickler noch lernen, wie die API korrekt aufgerufen werden muss. Ein fehlender Pflichtparameter im Request-Body liefert sofort eine 422-Antwort mit einer Fehlermeldung, die genau die verletzte Schema-Regel benennt.

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

# Start mock server from local OpenAPI spec
prism mock ./api-spec.yaml

# Start with request validation enabled (422 on invalid requests)
prism mock ./api-spec.yaml --errors

# Start from remote spec (e.g. from NelmioApiDocBundle export)
prism mock https://api.mironsoft.de/api/doc/public.json

# Start on custom port with verbose logging
prism mock ./api-spec.yaml --port 4010 --log-level debug

# Check available endpoints after startup
curl -s http://localhost:4010/api/v1/products | jq .

3. Realistische Beispieldaten mit OpenAPI examples

Automatisch generierte Zufallsdaten sind für einfache Checks ausreichend, für realistische UI-Tests aber ungeeignet. Ein Produktname wie mock-7a3f oder eine ID wie 9999999 verhindert, dass man im Frontend beurteilen kann, ob ein Produktkatalog gut aussieht. OpenAPI 3.x bietet zwei Mechanismen für realistische Beispieldaten: das example-Feld (ein einzelnes Beispiel) und das examples-Feld (ein benanntes Dictionary mit mehreren Szenarien).

Prism wählt bei mehreren definierten Examples das erste oder eines nach Zufallsprinzip aus — außer man gibt per Prefer: example=leeres-ergebnis-Header an, welches Beispiel zurückgegeben werden soll. Dieser Prefer-Header ist ein Prism-spezifischer Mechanismus, mit dem Frontend-Entwickler gezielt zwischen verschiedenen Szenarien wechseln können: Prefer: example=single-item für ein einzelnes Element, Prefer: example=empty-list für eine leere Ergebnismenge. So deckt ein einziger Mock-Endpunkt alle UI-Zustände ab, die man testen muss.

# OpenAPI spec snippet — realistic examples for mock server
paths:
  /api/v1/products:
    get:
      summary: List products
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
              examples:
                with-items:
                  summary: "Non-empty product list"
                  value:
                    data:
                      - id: 1
                        name: "Premium Kaffeemaschine XL"
                        price: 249.99
                        stock: 12
                      - id: 2
                        name: "Espresso-Kanne 0.5L"
                        price: 34.50
                        stock: 0
                    total: 2
                    page: 1
                    perPage: 20
                empty-list:
                  summary: "No products found"
                  value:
                    data: []
                    total: 0
                    page: 1
                    perPage: 20

4. Fehlerszenarien und Edge Cases simulieren

Die wichtigsten UI-Zustände sind oft die, die selten vorkommen: ein Netzwerkfehler, ein 401 nach abgelaufenem Token, ein 429 wegen zu vieler Anfragen, ein 503 während eines Backend-Deployments. In der Produktion passieren diese Fehler — in der Entwicklung werden sie systematisch ignoriert, weil man keinen einfachen Weg hat, sie zu provozieren. Ein Mock-Server mit expliziten Fehler-Examples löst dieses Problem vollständig.

Prism kann über den Prefer: status=503-Header angewiesen werden, einen spezifischen HTTP-Statuscode zurückzugeben, ohne dass dafür ein gesonderter Endpunkt konfiguriert werden muss. Die Antwort kommt dann aus dem passenden Response-Schema der Spec, also inklusive korrektem Error-Response-Body. So lässt sich in wenigen Sekunden testen, ob das Frontend einen 503 mit einem sinnvollen Fehlerdialog behandelt oder ob es stillschweigend hängen bleibt — ohne eine einzige Zeile Backend-Code zu ändern.

5. MSW: Mock Service Worker für Browser und Node

Mock Service Worker (MSW) ist eine Alternative zu Prism, die direkt im Browser oder in Node-Testumgebungen läuft und dort HTTP-Requests abfängt — ohne separaten Server-Prozess. MSW nutzt im Browser den Service-Worker-API, um Fetch- und XHR-Requests zu intercepten und mit definierten Handlern zu beantworten. Das macht es zur idealen Wahl für Unit- und Integrationstests mit Jest oder Vitest, wo ein externer Server-Prozess zu komplex wäre.

MSW unterstützt ab Version 2.x den @mswjs/source-Adapter, der Handler direkt aus einer OpenAPI-Spec generiert. So muss man die Mock-Handler nicht von Hand schreiben, sondern pflegt nur die Spec — und die Handler bleiben immer synchron. Für Szenarien, die über die Spec hinausgehen (stateful Mocks, die Request-Sequenzen verfolgen), erlaubt MSW eigene Handler-Logik in TypeScript, die über den generierten Basishandler gelegt wird.

6. Mock-Server als Docker-Service im Dev-Stack

Wer im Team mit Docker Compose arbeitet, kann den Prism-Mock-Server als zusätzlichen Service in die compose.dev.yaml aufnehmen. Jeder Entwickler, der docker compose up ausführt, bekommt automatisch einen laufenden Mock-Server auf dem definierten Port — ohne manuelle Schritte. Die OpenAPI-Spec liegt im Repository und wird als Volume in den Container gemountet, sodass Änderungen an der Spec nach einem Container-Neustart sofort verfügbar sind.

Die Umgebungsvariable VITE_API_BASE_URL (oder das jeweilige Frontend-Framework-Äquivalent) zeigt in der Entwicklungsumgebung auf den Mock-Server, in Staging und Produktion auf die echte API. Diese Konfiguration kostet einmal Aufwand beim Aufsetzen, spart danach in jedem Sprint mehrere Stunden Frontend-Entwicklungszeit, die sonst mit dem Warten auf oder Imitieren von Backend-Endpunkten verloren geht.

# compose.dev.yaml — Prism mock server as dev service
services:
  mock-api:
    image: stoplight/prism:4
    command: mock /tmp/api-spec.yaml --port 4010 --host 0.0.0.0 --errors
    volumes:
      - ./api-spec.yaml:/tmp/api-spec.yaml:ro
    ports:
      - "4010:4010"
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:4010"]
      interval: 10s
      timeout: 5s
      retries: 3

  frontend:
    build: ./frontend
    environment:
      VITE_API_BASE_URL: http://mock-api:4010
    depends_on:
      mock-api:
        condition: service_healthy
    ports:
      - "5173:5173"

7. Contract-Testing: Spec als Source of Truth

Contract-Testing stellt sicher, dass Backend-Implementierung und Frontend-Erwartungen zur gleichen Spec konform sind. Tools wie Dredd oder schemathesis nehmen eine OpenAPI-Spec und senden automatisch generierte Requests an den echten Backend-Server — und prüfen, ob die Antworten das definierte Schema erfüllen. Das ist das Gegenstück zum Mock-Server: Während der Mock-Server das Frontend von Backend-Abhängigkeiten entkoppelt, validiert Contract-Testing, dass das Backend wirklich die versprochene API liefert.

Schemathesis ist dabei besonders leistungsfähig, weil es Property-Based-Testing-Strategien einsetzt: Es generiert nicht nur die in der Spec definierten Examples, sondern systematisch Grenzwerte und Kombinationen, die Edge Cases im Backend aufdecken. Ein Integer-Parameter mit minimum: 1 wird mit 0, -1 und sehr großen Werten getestet. Strings mit maxLength: 255 werden mit 256 Zeichen getestet. So findet schemathesis Implementierungsfehler, die bei manuellen Tests nicht aufgefallen wären.

8. Netzwerklatenz und Rate-Limiting simulieren

Eine häufige Schwäche von Frontend-Implementierungen zeigt sich erst unter realistischen Netzwerkbedingungen: Loading-States, die zu früh verschwinden, Race Conditions bei parallelen Requests, fehlende Retry-Logik nach Timeouts. Ein Mock-Server, der immer sofort antwortet, deckt diese Probleme nicht auf. Prism selbst bietet keine eingebaute Latenz-Simulation — dafür gibt es toxiproxy von Shopify oder tc unter Linux, die als Netzwerk-Proxy vor den Mock-Server geschaltet werden und Latenz, Packet Loss und Bandbreitenbeschränkung simulieren.

Für Browsertests ist der Chrome-DevTools-Netzwerk-Throttling-Tab die einfachste Option, um langsame Verbindungen zu simulieren. In automatisierten Tests mit Playwright oder Cypress lässt sich die Netzwerklatenz programmatisch setzen. Kombiniert mit MSW, der Rate-Limit-Antworten (429) nach einer konfigurierbaren Anzahl von Requests zurückgibt, lässt sich ein vollständiges Resilienz-Test-Szenario aufbauen — ohne dass das Backend dafür eine einzige Zeile implementiert hat.

9. Mock-Strategien im Vergleich

Die Wahl des richtigen Mock-Ansatzes hängt von der Situation ab: Unit-Tests in Jest brauchen etwas anderes als manuelle Frontend-Entwicklung oder automatisierte Integrationstests in der CI-Pipeline.

Prism und MSW schließen sich nicht gegenseitig aus — sie lösen verschiedene Probleme. Prism als Docker-Service im Dev-Stack für manuelle Entwicklung, MSW in der Testsuite für automatisierte Unit- und Integrationstests. Wer beide einsetzt, hat die beste Abdeckung und maximale Unabhängigkeit vom Backend-Entwicklungsstand.

10. Zusammenfassung

Ein OpenAPI Mock-Server entkoppelt Frontend-Entwicklung vollständig von der Backend-Bereitschaft. Prism startet in einer Zeile aus jeder validen OpenAPI-Spec und liefert sofort realistische Antworten inklusive Schema-Validierung. MSW bringt dieselbe Entkopplung in Jest- und Vitest-Testsuiten, ohne externen Server-Prozess. Als Docker-Service im Dev-Stack steht der Mock-Server jedem Teammitglied automatisch zur Verfügung. Contract-Testing mit Schemathesis schließt den Kreis: Die Spec, die als Mock-Basis diente, wird zum Maßstab, an dem das fertige Backend gemessen wird.

Der entscheidende Schritt ist, die OpenAPI-Spec früh — idealerweise vor der ersten Zeile Implementierungscode — in ausreichender Detailtiefe zu definieren. Endpunkte, Request-Schemas, Response-Schemas und realistische Examples müssen vorhanden sein, damit der Mock-Server nützliche Antworten liefert. Diese Design-first-Investition zahlt sich in jedem darauffolgenden Sprint aus: Frontend-Teams können vollständig unabhängig arbeiten, Fehlerszenarien werden systematisch getestet, und das Backend muss beim Deployment nur noch die Spec erfüllen — nicht neu kommunizieren, was die API können soll.

11. FAQ: OpenAPI Mock-Server für Frontend-Entwicklung