API gegen Spezifikation validieren ohne Dredd

Dredd löst ein echtes Problem, und es löst es sauber. Sie richten es auf eine API-Beschreibung, ein OpenAPI-Dokument oder eine API Blueprint-Datei und auf einen laufenden Server. Es liest jedes Beispiel in der Beschreibung, sendet die passende Anfrage an das Live-Backend und überprüft, ob die tatsächliche Antwort dem entspricht, was die Spezifikation versprochen hat. Wenn Ihre Spezifikation besagt, dass GET /orders/{id} einen 200-Status mit einem id- und einem status-Feld zurückgibt, bestätigt Dredd, dass der laufende Dienst dies tatsächlich tut. Die Spezifikation hört auf, Dokumentation zu sein, die leise verrottet, und wird zu einem Test, der lautstark fehlschlägt.

Diese Idee, die Implementierung anhand der API-Beschreibung zu validieren, ist die richtige Idee. Die Abweichung zwischen dem, was eine Spezifikation besagt, und dem, was ein Dienst tut, ist einer der teuersten stillen Fehler in der API-Arbeit. Ein Frontend-Team programmiert gegen den dokumentierten Vertrag, das Backend liefert eine Feldumbenennung, niemand aktualisiert die Dokumentation, und der Bruch tritt in der Produktion auf. Dredd fängt genau diese Art von Fehler ab, und seit Jahren ist es das beliebteste Open-Source-Tool, um dies von der Befehlszeile aus zu tun.

Die Reibung liegt in der Einrichtung und Wartung, nicht im Konzept. Dredd ist eine Node.js CLI, die ihre eigene Konfigurationsdatei, eine Hooks-Datei in Ihrer bevorzugten Sprache für alles, was über triviale Fälle hinausgeht, und ein separates Spezifikationsartefakt benötigt, das Sie manuell neben allem anderen pflegen. Wenn Sie dasselbe Ergebnis wünschen, das Dredd Ihnen bietet, ein CI-Gate, das fehlschlägt, wenn Ihre Implementierung nicht mehr ihrem OpenAPI-Vertrag entspricht, ohne eine Hooks-Toolchain aufzusetzen und ohne die Spezifikation als dritte, getrennte Datei zu führen, ist Apidog für diesen Workflow konzipiert. Es hält die Spezifikation, die Tests und die Validierung in einem Projekt und führt das Ganze headless über eine npm CLI aus. Dieser Leitfaden ist fair darüber, was Dredd gut macht, und klar darüber, wo der integrierte Ansatz gewinnt.

Was Dredd gut macht

Geben Sie Dredd zuerst die Ehre, denn es hat sich den Ruf verdient.

Es testet die Implementierung, nicht einen Mock. Das ist der Kern der Sache. Viele Tools validieren, ob Ihre OpenAPI-Datei wohlgeformt ist oder ob ein Mock-Server sich verhält. Dredd tut etwas Schwierigeres: Es trifft das tatsächlich laufende Backend und überprüft die zurückkommenden echten Bytes anhand der dokumentierten Beispiele. Ein erfolgreicher Dredd-Lauf bedeutet, dass Ihr bereitgestellter Dienst und Ihre Spezifikation jetzt übereinstimmen, nicht nur in der Theorie.

Es spricht sowohl API Blueprint als auch OpenAPI. Dredd entwickelte sich parallel zu API Blueprint, dem Markdown-basierten Beschreibungsformat, und fügte später Unterstützung für OpenAPI 2 und 3 hinzu. Wenn Sie eine Legacy Blueprint-Datei oder ein Swagger-Dokument haben, kann Dredd es ohne Konvertierungsschritt lesen.

Sprachunabhängige Hooks. Wenn die Standard-Anfrage-und-Vergleichs-Schleife nicht ausreicht, Sie Authentifizierungstoken benötigen, eine Datenbank vor einem Test initialisieren müssen, eine Transaktion überspringen müssen, lässt Dredd Sie Hooks schreiben. Der Hook-Handler läuft standardmäßig in Node, aber Dredd bietet Protokollunterstützung für Hooks in Python, Ruby, Go, PHP, Rust und mehr. Ihr Team schreibt die Setup-Logik in einer Sprache, die es bereits beherrscht.

Es ist Open Source und CI-freundlich. Dredd wird mit npm install -g dredd installiert, läuft als einzelner Befehl und beendet sich mit einem Wert ungleich Null, wenn eine Validierung fehlschlägt, sodass jedes CI-System einen Build daran festmachen kann. Es gibt kein SaaS-Konto, keine Sitzplatzpreise, nichts zu unterschreiben. Für ein Team, das eine selbst gehostete, skriptfähige Vertragsprüfung wünscht, ist das wichtig.

Nichts davon ist Füllmaterial. Dredd ist ein solides Werkzeug mit einer klaren Aufgabe. Die Frage ist, ob sein Modell, drei separate Artefakte und eine Hooks-Datei, dem entspricht, wie Sie tatsächlich arbeiten möchten.

Wo die Reibung liegt

Drei Kosten sind im Dredd-Modell gebündelt, und wie sehr sie schmerzen, hängt von Ihrer Einrichtung ab.

Die Spezifikation ist ein drittes Artefakt, das Sie manuell pflegen. Dredd validiert die Implementierung anhand einer Beschreibungsdatei, was genau richtig ist, aber diese Beschreibung lebt normalerweise getrennt von dem Ort, an dem Sie die API entwerfen und testen. Sie bearbeiten eine openapi.yaml manuell, Sie halten Ihre Testszenarien woanders und Sie halten den laufenden Dienst wieder woanders. Dredd überprüft zwei dieser drei gegeneinander. Die Spezifikation selbst präzise zu halten, ist immer noch eine manuelle Aufgabe, und eine Spezifikation, die stillschweigend von der Realität abgewichen ist, erzeugt einen Dredd-Lauf, der grün und falsch ist.

Hooks sind Code, den Sie schreiben und pflegen. Sobald Ihre API Authentifizierung, Reihenfolge oder Testdaten benötigt, reicht die beispielgesteuerte Schleife nicht mehr aus. Sie schreiben eine hooks.js (oder ein Python- oder Ruby-Äquivalent), verbinden sie über dredd.yml, und jetzt besitzen Sie eine zweite Codebasis, deren einzige Aufgabe es ist, die erste testbar zu machen. Für eine einfache schreibgeschützte API ist Dredd nahezu konfigurationsfrei. Für eine echte mit Logins und zustandsbehafteten Endpunkten wächst die Hooks-Datei, und es ist Klebstoff-Code unter einem anderen Namen.

Beispielgesteuerte Abdeckung weist Lücken auf. Dredd testet die in Ihrer Beschreibung vorhandenen Beispiele. Wenn ein Endpunkt eine dokumentierte Beispielantwort hat, wird diese überprüft. Randfälle, Fehlerpfade und Validierungsregeln, die nicht als Beispiele in der Spezifikation aufgeführt sind, werden nicht getestet, es sei denn, Sie fügen sie hinzu, indem Sie die Spezifikation erweitern oder mehr Hooks schreiben. Die Abdeckung ist genau so gut wie die Beispiele, die Sie pflegen, nicht besser.

Der integrierte Pfad: Spezifikation und Tests in einem Projekt

Hier ist der andere Ansatz, den Apidog verfolgt. Die API-Definition ist keine dritte Datei, die Sie manuell synchronisieren; sie ist die Quelle der Wahrheit, die im selben Projekt wie die Tests, die sie ausführen, und die Validierung, die Ihren Build steuert, lebt. Ändern Sie das Schema, und die Tests sehen die neue Form. Es gibt keine separate openapi.yaml, die in einer Ecke des Repositorys herumtreibt, und keine Hooks-Datei, die zwischen der Spezifikation und einem funktionierenden Test steht.

Sie entwerfen oder importieren die API einmal. Apidog liest OpenAPI 2 und 3, importiert ein Swagger-Dokument und zieht Postman-Sammlungen mit einem Klick herein. Die Endpunkte, die Anforderungsschemata, die Antwortschemata und die Beispielantworten befinden sich alle in einem Projekt. Wenn Sie bereits spezifikationszentriert denken, ist dies dieselbe Disziplin, die Dredd fördert, nur ohne dass die Spezifikation eine lose Datei ist. Die tiefere Version dieses Workflows findet sich in der spezifikationszentrierten API-Entwicklung, und wenn Sie das Spezifikationsdokument selbst vor jedem Testlauf validieren möchten, deckt die Validierung von OpenAPI-Spezifikationen diesen Schritt ab.

Sie bauen die Validierung gegen diese realen Schemata auf. Wenn ein Testszenario GET /orders/{id} aufruft, behaupten Sie die Antwort gegen das Schema, das Apidog bereits für diesen Endpunkt hält, nicht gegen ein manuell kopiertes Beispiel. Das ist die Spezifikations-versus-Implementierungs-Prüfung, die Dredd durchführt, mit einem Unterschied: Die geprüfte Spezifikation ist dasselbe Objekt, von dem aus Sie die API entworfen haben, sodass sie nicht stillschweigend aus dem Takt mit Ihrer Testsuite geraten kann. Dies ist Vertragsprüfung ohne ein drittes Artefakt, und wenn Sie ein breiteres Bild dieser Disziplin wünschen, gehen API-Vertragsprüfung und bidirektionale Vertragsprüfung beide tiefer.

Einrichtung, die Dredd mit einer Hooks-Datei, Authentifizierungstoken, Reihenfolge, Seeding handhabt, handhaben Sie mit Pre- und Post-Request-Skripten in JavaScript, die die meisten Webentwickler bereits schreiben. Keine separate Hooks-Codebasis, die über eine Konfigurationsdatei verdrahtet ist. Die Logik lebt neben dem Test, den sie unterstützt.

Installation und Ausführung der Apidog CLI

Der Runner wird unter apidog-cli auf npm veröffentlicht. Wenn Sie Node.js haben, haben Sie alles, was Sie brauchen:

npm install -g apidog-cli

Die ausführbare Datei ist apidog, sodass jeder Lauf mit apidog run beginnt. Um ein Testszenario auszuführen, übergeben Sie ein Zugriffstoken, die Szenario-ID und die Umgebungs-ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Sie geben diese IDs nicht manuell ein. Öffnen Sie das Testszenario in Apidog, gehen Sie zum CI/CD-Tab, wählen Sie die Kommandozeilenoption und generieren Sie ein Zugriffstoken. Apidog erstellt den vollständigen apidog run-Befehl für Sie, wobei die Szenario- und Umgebungs-IDs bereits ausgefüllt sind. Kopieren Sie ihn einmal und parametrieren Sie das Token von dort aus. Behandeln Sie das Zugriffstoken wie ein Passwort: Speichern Sie es als Geheimnis in Ihrem CI-System und verweisen Sie darauf als $APIDOG_ACCESS_TOKEN, wie es jedes Beispiel hier tut.

Um mehr als ein Szenario auszuführen, richten Sie den Runner auf einen Ordner oder eine Testsuite anstatt auf eine einzelne ID und wählen Sie Ihre Reporter aus:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

Dieses -r-Flag wählt Reporter aus. Apidog unterstützt cli für lesbare Terminalausgaben, html für einen eigenständigen Bericht, den Sie als Build-Artefakt archivieren, junit für das XML, das fast jedes CI-Dashboard in einen Bestanden/Fehlgeschlagen-Baum parst, und json für rohe strukturierte Ergebnisse. Wenn Sie eine tiefere Einführung in den Runner wünschen, führen Sie apidog run --help für die vollständige Flag-Liste aus.

Seite an Seite

Lesen Sie diese Tabelle ehrlich. Wenn Sie ein vollständig selbst gehostetes, Open-Source-Tool ohne Konto wünschen und Ihr Team sich mit der Pflege einer Hooks-Datei wohlfühlt, passt Dredds Modell sauber, und ein Wechsel um des Wechsels willen bringt Ihnen nichts. Der Fall für den integrierten Pfad ist spezifisch: Sie sind es leid, dass die Spezifikation eine dritte Datei ist, die abweicht, Sie möchten keine Hooks-Codebasis besitzen, oder Sie möchten, dass dasselbe Projekt Design, Tests und die Vertragsprüfung gemeinsam handhabt.

Integration in CI

Die Apidog CLI beendet sich mit Null bei Erfolg und ungleich Null bei Fehler, sodass jedes CI-System einen Build daran festmachen kann, genau wie Dredd. Ein minimaler GitHub Actions Job benötigt Node und einen Ausführungsschritt:

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Das ist die gesamte Pipeline. Ein Dredd-Job sieht ähnlich aus: CLI installieren, einen Befehl ausführen, aber Sie richten ihn auch auf Ihre Spezifikationsdatei und Ihre Hooks-Datei, und Sie halten beide aktuell. Die Validierung läuft auf die gleiche Weise; der Unterschied liegt in der Anzahl der Artefakte, die Sie pflegen müssen, um dorthin zu gelangen.

Wenn Ihr Grund, Dredd zu verwenden, wirklich darin bestand, eine Spezifikation und einen Dienst ehrlich zueinander zu halten, taucht dieselbe Logik auch in anderen Tools auf. Teams stoßen auf Abweichungen zwischen Swagger und Postman, was OpenAPI-gesteuertes Testen gegen Swagger- und Postman-Drift abdeckt, und Java-Shops stoßen damit auf Rest Assured, wobei die Geschichte der Alternativen sich reimt: ein starkes Tool, dessen Modell eine Ebene hinzufügt, die Sie möglicherweise nicht möchten. Sie können Apidog auch von Ihrem Editor aus mit der VS Code-Erweiterung steuern, wenn Sie Ihre IDE nicht verlassen möchten.

Häufig gestellte Fragen

Ist Apidog ein direkter Ersatz für ein Dredd-Setup? Nein, und es gibt nicht vor, dies zu sein. Es gibt keinen Konverter, der Ihre dredd.yml und hooks.js liest und Apidog-Szenarien ausgibt. Sie importieren Ihre OpenAPI-Spezifikation und bauen die Validierung im visuellen Editor neu auf. Der Vorteil ist, dass Sie keine Hooks-Datei und lose Spezifikation mehr pflegen müssen; die Kosten sind ein einmaliger Neuaufbau. Wenn Sie eine große, ausgereifte Dredd-Suite haben, die funktioniert, ist dieser Neuaufbau eine echte Entscheidung, kein kostenloses Mittagessen.

Validiert Apidog die Live-Implementierung, so wie Dredd es tut? Ja. Die CLI sendet echte Anfragen an Ihren laufenden Dienst und behauptet die tatsächlichen Antworten gegen die Schemata in Ihrem Projekt. Das ist dieselbe Spezifikations-versus-Implementierungs-Prüfung, die Dredd durchführt. Der Unterschied ist, dass das geprüfte Schema dasjenige ist, von dem aus Sie die API entworfen haben, sodass es nicht von Ihren Tests abweichen kann.

Kann ich Authentifizierung und Test-Setup immer noch so handhaben, wie Dredd-Hooks es mir ermöglichen? Ja. Apidog unterstützt Pre-Request- und Post-Request-Skripte in JavaScript, sodass Sie Authentifizierungstoken abrufen, Daten initialisieren, Payloads transformieren oder dynamische Assertions im Code erstellen können. Die Logik lebt im Szenario, das sie unterstützt, anstatt in einer separaten Hooks-Datei, die über die Konfiguration verdrahtet ist.

Tut Dredd etwas, was Apidog nicht tut? Ein paar Dinge. Dredd ist vollständig selbst gehostet und Open Source ohne Konto, und es liest API Blueprint, das ältere Markdown-Beschreibungsformat, nativ. Wenn ein kontofreies, vollständig lokales Tool oder eine Legacy Blueprint-Datei für Ihr Setup zentral ist, wägen Sie das sorgfältig ab, bevor Sie wechseln.

Welches Format liest Apidog? OpenAPI 2 und 3, Swagger-Dokumente und Postman-Sammlungen, alle in ein Projekt importierbar. Wenn Sie zuerst die Formatunterschiede verstehen möchten, legen Swagger versus OpenAPI und die OpenAPI-Spezifikationsübersicht beide dar.

Fazit

Dredd hat die Kernidee richtig verstanden: Ihre API-Beschreibung sollte etwas sein, gegen das Sie den laufenden Dienst testen, und nicht ein Dokument, das abweicht. Wenn Sie eine selbst gehostete, Open-Source-CLI wünschen und Sie gerne eine Spezifikationsdatei und eine Hooks-Datei pflegen, ist Dredd eine gute Wahl, und Sie sollten es weiterhin verwenden.

Der integrierte Pfad ist für den Fall gedacht, dass Sie diese Wartung loswerden möchten. Apidog hält die Spezifikation, die Tests und die Validierung in einem Projekt, sodass der von Ihnen geprüfte Vertrag derselbe ist, von dem aus Sie entworfen haben, und es führt das Ganze von apidog run aus, ohne dass Sie eine Hooks-Codebasis besitzen müssen. Laden Sie Apidog herunter und importieren Sie Ihre bestehende OpenAPI-Datei, um die Spezifikations-versus-Implementierungs-Prüfung mit einem einzigen Befehl auszuführen.