DEV Community

Cover image for Wie man APIs per CLI mockt
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Wie man APIs per CLI mockt

Sie benötigen eine gefälschte API, gegen die Sie entwickeln können: Das Backend ist noch nicht verfügbar, ein Drittanbieterdienst ist ratenbegrenzt oder Tests sollen ohne Live-Server laufen. Mit einem CLI-basierten Mock machen Sie diesen Aufbau reproduzierbar: als Skript, CI-Schritt oder Befehl für einen KI-Code-Agenten.

Testen Sie Apidog noch heute

Manuell in einer Desktop-GUI angelegte Mocks sind für erste Experimente praktisch, aber schwer zu versionieren und nicht zuverlässig automatisierbar. Ein CLI-Mock dagegen wird aus einer Datei und einem Befehl erzeugt. Genau diesen Befehl kann Ihr Team lokal, in CI und in Agent-Workflows wiederverwenden.

Dieser Leitfaden zeigt zwei Wege:

  1. Open-Source-Tools, die lokal einen Mock-Server aus einer OpenAPI- oder JSON-Datei starten.
  2. Den Apidog CLI-Workflow, bei dem Sie Spezifikationen importieren und gehostete Mock-Erwartungen per CLI verwalten.

Für einen Tool-Vergleich finden Sie außerdem eine Übersicht der besten API-Mock-Tools sowie einen Leitfaden zu REST API Mocking Tools.

Der allgemeine Weg: Mock-Server aus einer Datei starten

Ein klassischer CLI-Mock ist ein kleines Tool, das eine Datei liest und daraus HTTP-Endpunkte bereitstellt. Sie benötigen dafür weder ein Projekt noch einen Login:

  • OpenAPI-Datei vorhanden: Verwenden Sie Prism.
  • Mockoon-Umgebung oder visuell gepflegte Routen vorhanden: Verwenden Sie Mockoon CLI.
  • Keine Spezifikation vorhanden, aber Beispieldaten: Verwenden Sie json-server.

Prism: OpenAPI-Spezifikation lokal bereitstellen

Wenn Sie bereits eine OpenAPI-Datei haben, ist Prism von Stoplight ein direkter Einstieg. Das Tool liest paths, Beispiele und Schemas aus Ihrer Spezifikation und liefert vertragskonforme Antworten.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Prism startet standardmäßig unter http://127.0.0.1:4010. Prüfen Sie den Mock anschließend direkt mit curl:

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Prism verwendet bevorzugt definierte example-Werte. Fehlen Beispiele, generiert es Daten aus dem Schema. Eingehende Anfragen werden außerdem gegen die Spezifikation validiert. Ein ungültiger Request führt damit beispielsweise zu 422, statt unbemerkt durchzulaufen.

Für eine globale Installation:

npm install -g @stoplight/prism-cli
prism mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Wichtig: Prism ist zustandslos. Ein POST speichert keine Daten für spätere GET-Anfragen. Das ist sinnvoll für vertragsorientierte Tests, aber nicht für Workflows, die persistente Testdaten erwarten.

Mockoon CLI: Mockoon-Umgebung headless ausführen

Mockoon CLI startet eine Mockoon-Umgebung ohne Desktop-App. Sie können entweder eine aus der Mockoon-App exportierte Umgebungsdatei oder eine OpenAPI-Spezifikation verwenden.

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Standardmäßig läuft der Server auf Port 3000. Legen Sie bei Bedarf einen anderen Port fest:

npx @mockoon/cli start --data ./env.json --port 8080
Enter fullscreen mode Exit fullscreen mode

Die CLI kann ältere Mockoon-Dateien im Speicher migrieren, ohne die Originaldatei zu verändern. Für eine globale Installation:

npm install -g @mockoon/cli
mockoon-cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Mockoon CLI eignet sich besonders, wenn Sie Routen und Antworten visuell modellieren, sie anschließend aber reproduzierbar in CI oder auf einem Server starten möchten. Ein leichter Mock-Server für eine RESTful API ist häufig genau dieser Anwendungsfall.

json-server: REST-API direkt aus JSON erzeugen

Wenn noch keine Spezifikation existiert, ist json-server oft der schnellste Weg zu einer nutzbaren REST-API. Erstellen Sie zunächst eine db.json:

{
  "posts": [
    {
      "id": 1,
      "title": "Erster Beitrag",
      "published": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Starten Sie anschließend den Server:

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

Damit steht unter http://localhost:3000/posts eine REST-Ressource mit GET, POST, PUT, PATCH und DELETE bereit.

Im Unterschied zu Prism ist json-server zustandsbehaftet: Ein POST fügt einen Datensatz hinzu und schreibt ihn zurück in die JSON-Datei. Zusätzlich stehen Filterung, Sortierung und Paginierung über Abfrageparameter zur Verfügung.

Für eine globale Installation:

npm install -g json-server
json-server db.json
Enter fullscreen mode Exit fullscreen mode

Wann der lokale Open-Source-Weg passt

Alle drei Tools starten einen lokalen Prozess aus einer Datei. Das ist ideal für schnelle, isolierte oder wegwerfbare Mocks.

Der Nachteil: Mock, API-Design, Tests und Dokumentation können getrennt voneinander gepflegt werden. Sie müssen Spezifikation, Mock-Dateien und laufende Prozesse selbst synchron halten. Für exaktes Request-Matching oder Replay gehen MockServer und WireMock weiter, benötigen jedoch eine Java-Laufzeitumgebung.

Der Apidog CLI-Pfad: Spezifikation importieren, Erwartungen skripten

Apidog arbeitet anders als lokale CLI-Mock-Server. Die apidog CLI startet keinen lokalen Mock-Prozess aus einer Datei. Ein Befehl wie dieser existiert nicht:

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Stattdessen hostet Apidog den Mock. Die CLI importiert Ihre API-Definition und verwaltet anschließend benutzerdefinierte Mock-Erwartungen.

Apidog ist nicht Open Source, sondern ein kommerzielles Produkt mit kostenlosem Tarif. Der zentrale Unterschied besteht darin, dass Mock, API-Design und Tests in einem gemeinsamen Projekt liegen können. Wenn Sie lediglich einen lokalen Einmal-Mock benötigen, sind Prism, Mockoon CLI oder json-server meist einfacher. Wenn der Mock mit Ihrer API-Definition mitwachsen soll, ist der folgende Workflow relevant.

Installieren und authentifizieren Sie zuerst die CLI. Die Token-Einrichtung beschreibt der Apidog CLI-Installationsleitfaden.

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

OpenAPI importieren und gehostete Smart Mocks erhalten

Importieren Sie Ihre Spezifikation in ein bestehendes Projekt:

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Nach dem Import stellt Apidog für die Operationen gehostete Mock-URLs bereit. Smart Mock verwendet Feldtypen und Feldnamen aus Ihrem Schema: Ein Feld wie email kann eine plausible E-Mail-Adresse liefern, createdAt einen realistisch formatierten Zeitstempel.

Neben OpenAPI unterstützt apidog import auch Swagger 2.0-, Postman- und Apidog-Formate.

Benutzerdefinierte Mock-Erwartungen verwalten

Automatisch generierte Antworten reichen für Standardfälle. Für gezielte Szenarien benötigen Sie benutzerdefinierte Erwartungen, etwa:

  • Benutzer-ID 123 liefert 200.
  • Benutzer-ID 404 liefert 404.
  • Ein bestimmter Header löst eine spezielle Fehlerantwort aus.

Die Befehlsgruppe apidog mock verwaltet diese Erwartungen als CRUD-Ressourcen. Sie startet keinen Server.

apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

Die Ausgabe ist strukturiertes JSON und kann beispielsweise mit jq weiterverarbeitet werden:

apidog mock list --project <PROJECT_ID> | jq .
Enter fullscreen mode Exit fullscreen mode

Zum Lesen, Aktualisieren oder Löschen verwenden Sie:

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Die Befehle create und update verwenden eine Datei, die die Erwartung beschreibt.

Erwartungsdatei vor dem Schreiben validieren

Raten Sie das Format von mock.json nicht. Die CLI stellt für Schreiboperationen ein Schema bereit. Holen Sie das Schema ab, erstellen Sie die Datei darauf basierend und validieren Sie sie vor dem Upload.

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Für Updates verwenden Sie denselben Ablauf mit mock-update:

apidog cli-schema get mock-update
apidog cli-schema validate mock-update --file ./mock.json
apidog mock update --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Dieser Ablauf ist CI-tauglich: Liefert die Validierung einen Exit-Code ungleich 0, stoppt die Pipeline, bevor eine fehlerhafte Erwartung in Ihr Projekt geschrieben wird.

Die Befehle geben außerdem JSON mit einem Block agentHints.nextSteps zurück. Dadurch können auch KI-Coding-Tools den Ablauf schrittweise ausführen. Weitere Befehlsgruppen beschreibt der vollständige Apidog CLI-Leitfaden.

Einbindung in CI

CLI-Mocks eignen sich für CI, weil sie über Exit-Codes und Textausgabe steuerbar sind.

Lokalen Prism-Mock im Testjob starten

Starten Sie Prism im Hintergrund, führen Sie Ihre Tests aus und beenden Sie den Prozess danach:

# Prism im Hintergrund starten, dann Tests dagegen ausführen
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

Apidog-Erwartungen vor Integrationstests anwenden

Bei Apidog gibt es keinen lokalen Prozess zum Starten oder Stoppen. Validieren und erstellen Sie die Erwartung als Setup-Schritt. Ihre Tests verwenden dann die gehostete Mock-URL.

# sicherstellen, dass die Erwartung wohlgeformt ist, dann anwenden
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Der entscheidende Vorteil beider Varianten: Niemand muss während eines Builds auf eine Schaltfläche klicken. Dasselbe Setup kann lokal, in CI und durch einen Agenten ausgeführt werden.

Häufige Fallstricke

Erwartung, dass apidog mock einen lokalen Server startet

Das passiert nicht. Es gibt kein apidog mock start, apidog mock serve oder apidog mock ./file.yaml.

Der korrekte Ablauf lautet:

  1. Spezifikation mit apidog import importieren.
  2. Gehostete Mocks verwenden.
  3. Benutzerdefinierte Antworten mit apidog mock verwalten.

Wenn Sie einen lokalen Prozess aus einer Datei starten möchten, verwenden Sie Prism, Mockoon CLI oder json-server.

Schema-Validierung bei Schreibvorgängen überspringen

apidog mock create und apidog mock update erwarten eine korrekt strukturierte Datei. Führen Sie daher immer zuerst diese Schritte aus:

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Die zusätzlichen Befehle vermeiden Debugging-Aufwand durch fehlerhafte Erwartungsdateien.

Prism liefert unbrauchbare oder leere Beispieldaten

Prism kann nur mit den Informationen arbeiten, die Ihre Spezifikation enthält. Wenn Antworten keine example-Werte und nur vage Schemas enthalten, sind auch die generierten Mock-Daten unpräzise.

Ergänzen Sie deshalb konkrete Beispiele:

responses:
  "200":
    description: Bestellung gefunden
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
        example:
          id: "123"
          status: "paid"
Enter fullscreen mode Exit fullscreen mode

Zustandsbehaftetes Verhalten von zustandslosen Mocks erwarten

Prism und die Vertrags-Mocks von Apidog speichern Schreibvorgänge nicht automatisch. Wenn ein POST anschließend über GET denselben neuen Datensatz liefern soll, verwenden Sie json-server oder definieren Sie gezielte Antworten über eine Apidog-Erwartung.

Zusammenfassung

CLI-basiertes Mocking macht aus einer manuellen Aufgabe einen versionierbaren und automatisierbaren Ablauf.

  • Prism: für OpenAPI-Spezifikationen und vertragsorientierte, lokale Mocks.
  • Mockoon CLI: für headless ausgeführte Mockoon-Umgebungen oder OpenAPI-Dateien.
  • json-server: für schnelle, zustandsbehaftete REST-APIs aus JSON.
  • Apidog CLI: für gehostete Mocks, die mit API-Design und Tests in einem Projekt verbunden bleiben.

Wählen Sie nach Ausgangslage und Zielumgebung. Für einen lokalen Wegwerf-Mock aus einer Datei sind die Open-Source-Tools ideal. Wenn Ihr Mock mit Design und Tests gemeinsam gepflegt werden soll, laden Sie Apidog herunter, installieren Sie die CLI und richten Sie Ihre Mocks vollständig per Skript ein.

Top comments (0)