DEV Community

Cover image for Was ist Specmatic?
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Was ist Specmatic?

Wenn Sie eine OpenAPI-Datei pflegen, Ihr laufender Dienst aber schrittweise davon abweicht, ist Specmatic für genau diese Lücke gedacht. Das Tool behandelt Ihre Spezifikation als ausführbaren Vertrag: Es testet einen echten Dienst dagegen und startet dieselbe Spezifikation als Stub-Server. In diesem Leitfaden sehen Sie, wie Specmatic praktisch eingesetzt wird, wie sich Vertragstests von beispielbasierten Tests unterscheiden und wo es im Vergleich zu einem breiteren Plattformansatz wie Apidogs API-Vertragstests passt. Die Quelle der Wahrheit bleibt dabei die OpenAPI Specification.

Probieren Sie Apidog noch heute aus

Was Specmatic ist

Specmatic ist ein Open-Source-Tool für vertragsgesteuerte API-Entwicklung. Die Grundidee: Ihre API-Spezifikation ist nicht nur Dokumentation, sondern ein ausführbarer Vertrag.

Mit einer OpenAPI-Datei kann Specmatic zwei Dinge tun:

  • Vertragstests ausführen: Specmatic testet einen laufenden Dienst gegen die Spezifikation.
  • Stub-Server starten: Specmatic simuliert einen Dienst, der gemäß Spezifikation antwortet.

Beide Modi lesen dieselbe Datei. Sie müssen also keine separate Testdefinition neben Ihrer OpenAPI-Spezifikation pflegen.

Specmatic unterstützt nicht nur OpenAPI. Seit Version 2.0 gehören auch GraphQL und gRPC dazu. Außerdem unterstützt es AsyncAPI für ereignisbasierte Verträge sowie Formate wie WSDL und Avro. Für viele Teams beginnt der Workflow trotzdem mit einer api.yaml oder api.json.

Typische Einsatzform:

# Lokal
specmatic test api.yaml --testBaseURL=http://localhost:8080

# In CI per Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080
Enter fullscreen mode Exit fullscreen mode

Vertragstests vs. beispielbasierte Tests

Beispielbasierte Tests prüfen einzelne manuell geschriebene Fälle:

GET /users/123
Enter fullscreen mode Exit fullscreen mode

Dann prüfen Sie z. B.:

  • Statuscode ist 200
  • Feld id existiert
  • Feld email ist ein String

Das funktioniert, skaliert aber schlecht. Wenn Ihre API 40 Endpunkte hat, müssen Sie viele Beispiele pflegen. Außerdem testen Sie nur das, woran Sie gedacht haben.

Vertragstests drehen das Modell um. Die Spezifikation beschreibt, was erlaubt ist. Specmatic liest diese Spezifikation und prüft automatisch, ob der Dienst dazu passt:

  • Stimmen Pfade und Methoden?
  • Stimmen Statuscodes?
  • Stimmen Response-Schemas?
  • Sind Pflichtfelder vorhanden?
  • Werden ungültige Requests korrekt abgelehnt?

Die Spezifikation ist damit nicht nur Dokumentation, sondern die Assertion.

Aspekt Beispielbasierte Tests Vertragstests mit Specmatic
Wahrheitsquelle Manuell geschriebene Testfälle OpenAPI-Spezifikation
Was Sie pflegen Requests und Assertions Die Spezifikation
Abdeckung Nur geschriebene Beispiele Operationen aus der Spezifikation
Drift-Erkennung Manuell Automatisch im Testlauf
Typischer Fehler Ein Beispiel schlägt fehl Dienst und Vertrag weichen ab

Wichtig ist außerdem die Unterscheidung zu Pact. Pact ist konsumentengesteuert: Konsumenten veröffentlichen Erwartungen, Anbieter validieren diese. Specmatic ist vertragsgesteuert: Eine Spezifikation ist der gemeinsame Vertrag, gegen den Anbieter getestet und für Konsumenten gestubbt wird.

Wenn Sie Tools in diesem Bereich vergleichen, hilft diese Übersicht zu API-Vertragstests und Mocking-Tools.

Specmatic installieren und ausführen

Sie können Specmatic entweder als CLI oder per Docker verwenden. Für lokale Tests ist die CLI bequem. Für CI/CD ist Docker oft einfacher, weil keine lokale Laufzeitumgebung vorbereitet werden muss.

Vertragstests gegen einen laufenden Dienst

Angenommen, Ihre API läuft lokal auf Port 8080 und Ihre Spezifikation liegt als api.yaml vor:

specmatic test api.yaml --testBaseURL=http://localhost:8080
Enter fullscreen mode Exit fullscreen mode

Mit Docker:

docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080
Enter fullscreen mode Exit fullscreen mode

Der Ablauf ist:

  1. Specmatic liest api.yaml.
  2. Es generiert Requests aus den beschriebenen Operationen.
  3. Es sendet diese Requests an --testBaseURL.
  4. Es validiert die Responses gegen die Spezifikation.
  5. Bei Abweichungen schlägt der Test fehl.

Ein fehlgeschlagener Test bedeutet: Entweder ist der Dienst falsch implementiert oder die Spezifikation ist veraltet. Beides sollten Sie korrigieren, bevor der Build weiterläuft.

Ein einfaches OpenAPI-Beispiel:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - email
                properties:
                  id:
                    type: string
                  email:
                    type: string
                    format: email
Enter fullscreen mode Exit fullscreen mode

Wenn der Dienst für GET /users/123 z. B. kein email-Feld zurückgibt, erkennt Specmatic die Abweichung.

Specmatic in CI integrieren

Ein typischer CI-Schritt besteht aus drei Teilen:

  1. Service starten
  2. Warten, bis der Service erreichbar ist
  3. Specmatic-Test ausführen

Beispiel als generischer Shell-Step:

docker compose up -d api

until curl -f http://localhost:8080/health; do
  sleep 2
done

docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080
Enter fullscreen mode Exit fullscreen mode

Damit wird API-Drift automatisch zu einem Build-Fehler. Das ist besonders nützlich, wenn mehrere Teams dieselbe API konsumieren oder wenn Microservices unabhängig deployed werden.

Die Spezifikation als Stub ausführen

Die zweite zentrale Funktion ist der Stub-Server. Damit können Konsumenten gegen eine API entwickeln, bevor der echte Anbieter fertig ist.

specmatic stub api.yaml --port=9000
Enter fullscreen mode Exit fullscreen mode

Danach kann ein Frontend oder ein anderer Dienst gegen den Stub sprechen:

curl http://localhost:9000/users/123
Enter fullscreen mode Exit fullscreen mode

Specmatic generiert standardmäßig schema-gültige Antworten. Wenn Sie kontrollierte Beispieldaten brauchen, können Sie Beispiele neben der Spezifikation in einem _examples-Verzeichnis ablegen. Der Stub gibt diese zurück, wenn der Request passt.

Das ist praktisch für:

  • Frontend-Entwicklung ohne fertiges Backend
  • Consumer-Tests ohne externe Abhängigkeiten
  • Reproduzierbare Testdaten
  • Lokales Arbeiten ohne komplette Umgebung

Wenn Sie Stub- und Mock-Ansätze vergleichen möchten, ordnet diese Übersicht zu Vertragstests und Mock-Servern Specmatic ein.

Eine bestehende API zur Spezifikation machen

Specmatic kann auch helfen, wenn Sie bereits einen Dienst haben, aber noch keine vollständige OpenAPI-Spezifikation.

Dafür kann Specmatic als Proxy vor dem bestehenden Dienst laufen, echten Traffic beobachten und daraus ein OpenAPI-Dokument sowie Beispieldateien erzeugen. Das ist hilfreich, wenn Sie einen Legacy-Service schrittweise in einen Contract-First-Workflow überführen möchten.

Der praktische Ablauf ist:

  1. Specmatic als Proxy vor den Dienst setzen.
  2. Typische Requests gegen den Dienst ausführen.
  3. Erzeugte OpenAPI-Spezifikation prüfen.
  4. Fehlende Details manuell ergänzen.
  5. Danach specmatic test und specmatic stub verwenden.

Die generierte Spezifikation sollten Sie nicht blind übernehmen. Sie ist ein Startpunkt, keine vollständige fachliche Beschreibung Ihrer API.

Das Modell: eine Spezifikation, zwei Ausführungsarten

Der wichtigste Vorteil entsteht dadurch, dass dieselbe Datei sowohl für Tests als auch für Stubs verwendet wird.

Für Anbieter:

specmatic test api.yaml --testBaseURL=http://localhost:8080
Enter fullscreen mode Exit fullscreen mode

Für Konsumenten:

specmatic stub api.yaml --port=9000
Enter fullscreen mode Exit fullscreen mode

Damit arbeiten beide Seiten gegen denselben Vertrag:

  • Anbieter sehen sofort, wenn ihre Implementierung abweicht.
  • Konsumenten entwickeln gegen Antworten, die zur Spezifikation passen.
  • Änderungen am Vertrag werden explizit sichtbar.
  • Die Spezifikation wird zur lebenden Vereinbarung statt zur veralteten Dokumentation.

Wenn Sie genauer zwischen Stub und Mock unterscheiden möchten, lesen Sie API-Stubbing vs. Mocking.

Abwärtskompatibilität prüfen

Specmatic bietet auch eine Prüfung auf Abwärtskompatibilität. Der Befehl backward-compatibility-check vergleicht eine neue Version der Spezifikation mit einer vorherigen Version.

Das Prinzip:

  1. Specmatic startet einen Stub aus der neuen Spezifikation.
  2. Es generiert Tests aus der alten Spezifikation.
  3. Diese Tests laufen gegen den neuen Stub.
  4. Wenn bisher unterstütztes Verhalten nicht mehr funktioniert, schlägt die Prüfung fehl.

Das ist besonders wertvoll bei APIs, die von mehreren Konsumenten genutzt werden. Breaking Changes werden so früh sichtbar, bevor sie produktiv deployed werden.

Dieser Ansatz ist verwandt mit der breiteren Idee von bidirektionalen Vertragstests.

Wo Specmatic gut passt

Specmatic passt besonders gut, wenn Ihr Team:

  • eine gepflegte OpenAPI-, AsyncAPI-, GraphQL- oder gRPC-Spezifikation hat,
  • Anbieter- und Konsumententeams synchron halten muss,
  • API-Drift automatisch im Build erkennen möchte,
  • CLI- und CI-zentriert arbeitet,
  • Spezifikationen als technische Quelle der Wahrheit behandelt.

Ein typischer Workflow sieht so aus:

# 1. Spezifikation ändern
vim api.yaml

# 2. Stub für Konsumenten starten
specmatic stub api.yaml --port=9000

# 3. Anbieter implementiert Änderung

# 4. Vertragstest gegen echten Dienst
specmatic test api.yaml --testBaseURL=http://localhost:8080

# 5. In CI denselben Test ausführen
Enter fullscreen mode Exit fullscreen mode

Specmatic passt weniger gut, wenn Sie:

  • keine Spezifikation pflegen,
  • einen visuellen API-Designer benötigen,
  • Ad-hoc-Debugging, Dokumentation, Mocking und Teamzusammenarbeit in einem Tool erwarten,
  • speziell einen Pact-Broker für konsumentengesteuerte Verträge brauchen.

Specmatic konzentriert sich auf die Vertrags-Engine. Diese Aufgabe erfüllt es gezielt.

Specmatic und Apidog im Vergleich

Apidog verfolgt ebenfalls einen schemabasierten Ansatz. Es liest OpenAPI-Spezifikationen, validiert Antworten gegen Schemas und kann einen Mock-Server aus Ihrem OpenAPI-Schema starten.

Der Unterschied liegt im Umfang:

  • Specmatic ist ein CLI-natives Vertragstest- und Stub-Tool.
  • Apidog kombiniert Design, Tests, Mocking und Dokumentation in einem visuellen Arbeitsbereich.

Wenn Sie ausführbare Tests direkt aus einer Spezifikation in einem Workspace generieren möchten, sehen Sie sich an, wie Apidog die Generierung von API-Testsammlungen aus OpenAPI-Spezifikationen handhabt.

Wichtig: Apidog ist ebenso wenig wie Specmatic ein Pact-ähnlicher, konsumentengesteuerter Vertragsbroker. Wenn Ihr Team explizit Pact-Broker-Workflows braucht, ist Pact das passendere Modell.

Häufig gestellte Fragen

Ist Specmatic kostenlos?

Ja. Die Kern-Vertrags-Engine ist Open Source und kann kostenlos über CLI oder Docker verwendet werden. Es gibt kommerzielle Angebote rund um Specmatic, aber Vertragstests und Stub-Server aus OpenAPI-Spezifikationen können Sie kostenlos ausführen. Prüfen Sie für aktuelle Details die offizielle Website und das GitHub-Repository.

Funktioniert Specmatic nur mit OpenAPI?

Nein. OpenAPI ist der häufigste Einstiegspunkt, aber Specmatic unterstützt auch AsyncAPI für ereignisbasierte Verträge, GraphQL und gRPC seit Version 2.0 sowie Formate wie WSDL und Avro.

Das Modell bleibt gleich: Die Spezifikation ist der ausführbare Vertrag.

Wenn Sie mit OpenAPI starten, hilft dieses OpenAPI-Spezifikations-Tutorial.

Ist Specmatic dasselbe wie Pact?

Nicht ganz.

Pact ist konsumentengesteuert. Konsumenten veröffentlichen Erwartungen an einen Broker, Anbieter validieren diese Erwartungen.

Specmatic ist vertragsgesteuert. Eine Spezifikation ist der gemeinsame Vertrag. Specmatic validiert Anbieter dagegen und erzeugt daraus Stubs für Konsumenten.

Beide Ansätze reduzieren Integrationsprobleme, organisieren den Vertrag aber unterschiedlich.

Kann Specmatic eine OpenAPI-Spezifikation generieren?

Ja. Specmatic kann als Proxy vor einem bestehenden Dienst laufen, Request- und Response-Traffic erfassen und daraus ein OpenAPI-Dokument sowie Beispieldateien erzeugen.

Das ist nützlich, wenn ein Dienst bereits existiert, aber noch keine formale Spezifikation gepflegt wird.

Fazit

Specmatic löst ein konkretes Problem: Es hält einen laufenden Dienst ehrlich gegenüber der Spezifikation, der er folgen soll. Aus einer OpenAPI-Datei erhalten Sie Vertragstests, einen passenden Stub-Server und Prüfungen auf Abwärtskompatibilität.

Wenn Ihr Team terminal- und CI-orientiert arbeitet und eine solide Spezifikation pflegt, ist Specmatic ein passendes Werkzeug.

Wenn Sie Vertrag, Tests, Mock und Dokumentation lieber in einem visuellen Arbeitsbereich verwalten möchten, der dieselbe OpenAPI-Datei liest, probieren Sie Apidog aus. Apidog validiert Antworten gegen Ihr Schema, mockt Endpunkte ohne Code und wandelt Spezifikationen in ausführbare Testsammlungen um. Laden Sie Apidog herunter, um es mit Ihrer eigenen Spezifikation zu testen.

Top comments (0)