Swagger CLI: API-Spezifikationen validieren, linten und testen vom Terminal

Sie haben einen Pull-Request geöffnet, die Dokumente wurden einwandfrei erstellt, und drei Tage später meldet sich ein Teamkollege bei Ihnen: Der Staging-Server lehnt jede Anfrage ab, weil die OpenAPI-Datei einen hängenden $ref enthält, der auf einen Pfad zeigt, den Sie umbenannt haben. Die Spezifikation sah im Editor korrekt aus. Sie wurde in Swagger UI gerendert. Sie war aber tatsächlich nicht gültig, und nichts in Ihrer Pipeline hat dies vor der Auslieferung bemerkt.

Genau dafür ist ein Swagger-Kommandozeilen-Tool gebaut: um fehlerhafte Spezifikationen zu erkennen, bevor es ein Mensch tut. Der Begriff „swagger cli“ bezieht sich meist auf @apidevtools/swagger-cli, ein kleines npm-Paket, dessen zwei Befehle, validate und bundle, ein OpenAPI-Dokument prüfen und Multi-Datei-Spezifikationen zu einer einzigen zusammenfügen. Es ist ein wirklich nützliches Werkzeug, und dieser Leitfaden zeigt Ihnen, wie Sie es richtig verwenden. Er zeigt Ihnen auch, wo es an seine Grenzen stößt, denn die Validierung einer Spezifikation ist nur die erste Hälfte des Vertrauens in eine API; die zweite Hälfte besteht darin, echte Anfragen zu senden und zu überprüfen, was zurückkommt, und hier kommt ein Runner wie das Apidog CLI ins Spiel.

Es handelt sich also um die Arbeit von zwei Terminals. Zuerst überprüfen und bündeln Sie die Spezifikation mit swagger-cli (oder seinem Nachfolger), damit der Vertrag solide ist. Führen Sie dann tatsächliche Tests gegen die laufende API über die Kommandozeile aus, um sicherzustellen, dass die Implementierung dem Vertrag entspricht. Wir werden beides behandeln, ehrlich sein, welches Tool welche Aufgabe übernimmt, und Ihnen Copy-Paste-Befehle für jedes geben.

Was „swagger cli“ tatsächlich bedeutet

Es gibt kein einziges offizielles Binary namens „swagger“. Der Name bezieht sich auf verschiedene Tools, und zu wissen, welches Sie meinen, erspart viel Verwirrung.

• @apidevtools/swagger-cli ist das Paket, das die meisten Leute meinen. Sein Binary ist swagger-cli, und es erfüllt zwei Aufgaben: Validierung eines OpenAPI- oder Swagger 2.0-Dokuments und Bündelung einer Multi-Datei-Spezifikation in eine einzige Datei. Es ist der Schwerpunkt der ersten Hälfte dieses Artikels.
• swagger-codegen ist ein separates, viel größeres SmartBear-Projekt, das Client-SDKs und Server-Stubs aus einer Spezifikation generiert. Eine völlig andere Aufgabe; wir gehen am Ende darauf ein.
• Swagger UI und Swagger Editor sind überhaupt keine CLIs. Sie rendern und bearbeiten Spezifikationen in einem Browser. Wenn Sie das Format noch lernen, ist der Swagger- und OpenAPI-Primer der richtige Ausgangspunkt.

Dieser Leitfaden handelt von der Arbeit über die Kommandozeile: Validieren, Bündeln, Linting und dann Testen. Wenn Sie stattdessen einen breiteren Überblick über Design- und Testplattformen wünschen, behandelt der Swagger-Alternativen-Überblick die GUI-Seite.

swagger-cli installieren

Das Tool wird als npm-Paket ausgeliefert. Installieren Sie es global:

npm install -g @apidevtools/swagger-cli

Bestätigen Sie die Installation:

swagger-cli --version
swagger-cli --help

Node.js ist die einzige Systemabhängigkeit. Jede Maschine oder jedes CI-Image, auf dem Node bereits installiert ist, kann es ausführen. Wenn Sie es lieber nicht global installieren möchten, können Sie es bei Bedarf mit npx @apidevtools/swagger-cli ... aufrufen, was bei temporären Build-Runnern praktisch ist.

Eine Sache, die Sie wissen sollten, bevor Sie sich darauf verlassen: Die Maintainer haben swagger-cli als veraltet gekennzeichnet. Die README besagt dies unmissverständlich und nennt die Wartungslast einer großen Benutzerbasis mit wenigen Mitwirkenden als Grund. Es funktioniert immer noch, und viele Pipelines verwenden es heute, aber neue Projekte werden auf Redocly CLI als den aktiv gepflegten Nachfolger verwiesen. Wir behandeln diese Migration in einem eigenen Abschnitt weiter unten, damit Sie mit offenen Augen entscheiden können.

Eine Spezifikation mit swagger-cli validieren

Der wichtigste Befehl ist validate. Richten Sie ihn auf Ihre Spezifikationsdatei aus:

swagger-cli validate openapi.yaml

Wenn das Dokument in Ordnung ist, erhalten Sie eine einzeilige Bestätigung und einen Exit-Code von 0. Wenn etwas nicht stimmt, erhalten Sie eine Fehlermeldung, die das Problem beschreibt, und einen Exit-Code ungleich Null, was genau das ist, was Sie in einer Pipeline wünschen.

validate führt im Hintergrund zwei Prüfungen aus, und Sie können beide deaktivieren:

swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml

--no-schema überspringt die Validierung gegen das OpenAPI JSON Schema, die strukturelle Prüfung, die bestätigt, dass Ihr Dokument die richtige Form hat. --no-spec überspringt die Validierung gegen die Spezifikationsregeln selbst, die semantische Prüfung, die Dinge wie doppelte Operations-IDs oder einen $ref, der nirgendwohin zeigt, abfängt. Meistens möchten Sie beides aktiviert haben, was die Standardeinstellung ist. Die Flags existieren für den seltenen Fall, dass eine Ebene etwas markiert, das Sie aus einem bestimmten Grund zulassen möchten.

Was validate gut abfängt: fehlerhaftes YAML, fehlende Pflichtfelder, kaputte $ref-Zeiger und strukturelle Fehler, die eine Spezifikation unparsbar machen. Was es nicht tut, ist den Stil Ihres Teams durchzusetzen. Es wird eine Spezifikation ohne Beschreibungen, inkonsistente Benennung und ohne Beispiele problemlos bestehen lassen, da nichts davon die OpenAPI-Regeln bricht. Für diese Art von meinungsstarker Prüfung benötigen Sie einen Linter, der im nächsten Abschnitt behandelt wird.

Wenn die Validierung das Einzige ist, wofür Sie gekommen sind, vergleicht der ausführliche Leitfaden wie man OpenAPI-Spezifikationen validiert mehrere Tools und wissenswerte Grenzfälle.

Eine Multi-Datei-Spezifikation bündeln

Echte Spezifikationen befinden sich selten in einer einzigen Datei. Sie teilen Schemas in ein components/-Verzeichnis auf, referenzieren sie mit $ref und halten die Stammdatei lesbar. Das ist gute Praxis, aber viele nachgelagerte Tools wünschen ein einziges, eigenständiges Dokument. Der Befehl bundle glättet den Baum:

swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml

Die wissenswerten Flags:

• -o, --outfile <file> schreibt das Ergebnis in eine Datei, anstatt es in stdout auszugeben.
• -t, --type <json|yaml> legt das Ausgabeformat fest. Standardmäßig ist dies json, geben Sie also -t yaml an, wenn Sie YAML als Ausgabe wünschen.
• -r, --dereference bettet jeden $ref vollständig ein, anstatt nur externe Dateien in einem Dokument zu sammeln. Dies erzeugt eine größere Datei ohne verbleibende Referenzen, was einige Konsumenten erfordern.
• -f, --format <spaces> steuert die Einrückung, standardmäßig auf 2 Leerzeichen.
• -w, --wrap <column> legt die Zeilenlänge für das Umbrechen langer YAML-Strings fest.

Der Unterschied zwischen einem einfachen Bundle und --dereference ist wichtig. Ein normales Bundle behält interne $ref-Zeiger bei, zieht aber alle separaten Dateien in eine einzige zusammen, sodass das Dokument portabel ist. --dereference löst jede Referenz in Inline-Objekte auf, was die Dateigröße stark erhöht, aber garantiert, dass kein Konsument jemals einen Zeiger auflösen muss. Verwenden Sie das einfache Bundle für die Verteilung und die dereferenzierte Form nur, wenn ein bestimmtes Tool dies erfordert.

Ein gängiges Muster ist es, im Rahmen eines Builds in einem Schritt zu validieren und zu bündeln:

swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json

Das && bedeutet, dass das Bundle nur ausgeführt wird, wenn die Validierung erfolgreich ist, sodass eine fehlerhafte Spezifikation niemals ein Build-Artefakt erzeugt.

swagger-cli in CI einbinden

Validierung ist am wertvollsten, wenn sie bei jeder Änderung ausgeführt wird und nicht nur, wenn sich jemand daran erinnert. Fügen Sie sie als schnelles Gate in Ihre Pipeline ein. Hier ist ein GitHub Actions-Schritt, der den Build bei einer ungültigen Spezifikation fehlschlagen lässt:

name: Validate OpenAPI spec

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'components/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate spec
        run: npx @apidevtools/swagger-cli validate openapi.yaml

Da swagger-cli validate bei einer fehlerhaften Spezifikation mit einem Nicht-Null-Exit-Code beendet wird, wird der Schritt rot und der Pull-Request zeigt eine fehlgeschlagene Prüfung an. Keine zusätzliche Konfiguration. Der paths-Filter verhindert, dass der Job ausgeführt wird, wenn die Spezifikation nicht geändert wurde, was Ihre CI-Minuten reduziert.

Dies ist das günstigste Qualitäts-Gate, das Sie einem API-Repository hinzufügen können. Es kostet Sekunden und verhindert, dass eine ganze Klasse von „die Dokumente lügen“-Bugs jemanden nachgelagert erreicht.

Wann Sie Linting benötigen, nicht nur Validierung

Die Validierung beantwortet eine Frage: Ist dies ein gültiges OpenAPI-Dokument? Linting beantwortet eine schwierigere: Ist dies ein gutes OpenAPI-Dokument nach den Standards unseres Teams? Das ist nicht dasselbe, und swagger-cli macht nur Ersteres.

Angenommen, Ihr Styleguide verlangt, dass jede Operation einen summary, jede Eigenschaft eine description und jeder Pfad kebab-case verwendet. Eine Spezifikation kann alle drei verletzen und trotzdem swagger-cli validate bestehen, da keine dieser Regeln Teil der OpenAPI-Spezifikation ist. Ein Linter ermöglicht es Ihnen, diese zu kodieren und durchzusetzen.

Dies ist der Hauptgrund, warum Teams auf Redocly CLI umsteigen, den gepflegten Nachfolger, auf den swagger-cli selbst verweist. Es deckt dieselbe Validierung und Bündelung ab und fügt dann eine echte Linting-Engine hinzu.

Migration zu Redocly CLI

Die Migration ist gering, da die Befehlsnamen ähnlich sind. Installieren Sie den Nachfolger:

npm install -g @redocly/cli

Das Äquivalent zu validate ist lint. Um das alte Verhalten genau abzubilden, erweitern Sie den minimalen Regelsatz:

redocly lint --extends=minimal openapi.yaml

Führen Sie es stattdessen mit dem Standardregelsatz aus, und es erzwingt eine stärkere Reihe empfohlener Regeln, wo der Wert des Lintings zum Tragen kommt. Sie konfigurieren Regeln in einer redocly.yaml-Datei, setzen jede auf error oder warn und können sogar benutzerdefinierte Plugins für unternehmensspezifische Prüfungen schreiben.

Das Bündeln ist fast eins zu eins übertragbar:

redocly bundle openapi.yaml -o dist/openapi.yaml

Die Namen der Flags ändern sich geringfügig. swagger-clis -o/--outfile wird zu --output, -t/--type wird zu --ext, und -r/--dereference wird zu -d/--dereferenced. Wenn Ihre alten Skripte die Kurz-Flags verwendeten, bringt Sie ein schnelles Suchen und Ersetzen ans Ziel. Für einen breiteren Vergleich von Spezifikationsprüfungs-Tools stellt die Übersicht der besten OpenAPI-Validierungs-Tools Redocly neben die Alternativen.

Kurz gesagt: Wenn Sie ganz neu anfangen, greifen Sie zum Redocly CLI. Wenn Sie einen bestehenden swagger-cli-Schritt haben, der funktioniert, gibt es keinen Grund zur Eile, aber der Weg nach vorne ist klar und die Umbenennung ist mechanisch.

Der Bereich, den ein Spezifikations-Tool nicht abdecken kann

Hier ist die Grenze jedes Tools, das wir bisher besprochen haben. swagger-cli validate bestätigt, dass Ihre Spezifikation wohlgeformt ist. redocly lint bestätigt, dass sie Ihrem Stil entspricht. Keines von beiden sendet eine einzige Anfrage an Ihre laufende API. Eine Spezifikation kann auf dem Papier perfekt sein, während die Implementierung einen 500er-Fehler zurückgibt, ein versprochenes Feld weglässt oder einen Abfrageparameter vollständig ignoriert.

Diese Lücke zu schließen bedeutet funktionale Tests: Senden Sie eine echte Anfrage an einen echten Endpunkt und überprüfen Sie dann den Statuscode, den Antwortkörper und die darin enthaltenen Werte. Das ist eine andere Kategorie von Tools, und hier passt Apidog in den Workflow.

Apidog ist eine All-in-One-API-Plattform. Sie importieren Ihre OpenAPI-Spezifikation, und aus dieser einen Definition erhalten Sie interaktive Dokumente, einen Mock-Server und Testszenarien, die Sie mit Assertions miteinander verketten können, alles ohne den Arbeitsbereich zu verlassen. Der Import ist direkt; der Leitfaden zum Importieren von Swagger oder OpenAPI und Generieren ausführbarer Anfragen führt Sie durch diesen Prozess, und Sie können vollständige Testsammlungen direkt aus der Spezifikation generieren, anstatt sie manuell zu erstellen.

Das für das Terminal relevante Stück ist der Kommandozeilen-Runner, der als npm-Paket apidog-cli veröffentlicht wird. Sie installieren ihn und führen ein gespeichertes Szenario headless aus:

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

Das Flag -t ist die ID des Testszenarios, -e ist die Umgebung-ID, und -r wählt Berichtsformate wie cli, html, json oder junit. Wie swagger-cli beendet es sich mit einem sauberen Statuscode, sodass eine fehlerhafte Assertion die Pipeline rot färbt. Im Gegensatz zu swagger-cli prüft es jedoch das Live-Verhalten Ihrer API und nicht nur die Form der Datei, die sie beschreibt. Für die vollständige Flag-Referenz und CI-Beispiele siehe den Apidog CLI vollständigen Leitfaden, oder führen Sie apidog run --help für die aktuellen Optionen aus. Wenn Sie dieses erste Szenario einrichten möchten, laden Sie Apidog herunter, importieren Sie Ihre Spezifikation, und der Runner-Befehl ist eine Kopie von der CI/CD-Registerkarte des Szenarios.

Ein vollständiger Terminal-Workflow

Fügen Sie die beiden Hälften zusammen und Sie erhalten eine Pipeline, die den Vertrag und die Implementierung nacheinander prüft:

# 1. Ist die Spezifikation wohlgeformt und stilistisch korrekt?
redocly lint --extends=minimal openapi.yaml

# 2. Erzeugen Sie ein einzelnes verteilbares Dokument.
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. Entspricht die laufende API tatsächlich dem Vertrag?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

Schritt eins schlägt bei einer fehlerhaften oder stilistisch nicht konformen Spezifikation sofort fehl. Schritt zwei erzeugt das Artefakt, das Ihre Dokumente und SDK-Generatoren konsumieren. Schritt drei sendet echten Traffic und überprüft die Antworten, sodass ein erfolgreicher Build bedeutet, dass sowohl der Vertrag als auch der dahinterliegende Code solide sind. Jeder Schritt beendet sich bei Misserfolg mit einem Nicht-Null-Exit-Code, sodass die gesamte Kette ein einziges Gate ist, das Sie in jeden CI-Runner, der Node hat, einfügen können.

Wenn Ihre heutigen Tests auf einem Spezifikations-Konformitätstool basieren, das stillgelegt wurde, behandelt der Artikel über das Validieren einer API gegen ihre Spezifikation ohne Dredd dieselbe Idee des Vertrags-versus-Implementierung aus einem anderen Blickwinkel.

Ein Hinweis zu swagger-codegen

Personen, die nach einem „swagger cli“ suchen, möchten manchmal tatsächlich swagger-codegen, ein anderes Tool mit einer anderen Aufgabe. Es liest eine OpenAPI-Spezifikation und generiert Client-SDKs, Server-Stubs und Dokumentation in Dutzenden von Sprachen. Es ist wirklich nützlich, um einen typisierten Client aus einer veröffentlichten Spezifikation zu bootstrappen, und es ist fair, es als die leistungsfähigste Code-Generierungsoption in der Swagger-Familie zu bezeichnen.

Es validiert, lintet oder testet nicht in dem Sinne, wie es dieser Artikel behandelt. Die Generierung setzt voraus, dass Sie bereits eine solide Spezifikation haben; wenn der Input fehlerhaft ist, ist der Output in ähnlicher Weise fehlerhaft. Selbst in einem Codegen-Workflow möchten Sie also immer noch einen Validierungs- oder Lint-Schritt davor haben. Die Tools ergänzen sich gegenseitig, anstatt sich zu ersetzen.