Wenn Sie hier gelandet sind, nachdem Sie npm install -g @apidevtools/swagger-cli ausgeführt und die Warnungen bemerkt haben, hier die Kurzversion: Das Tool wird nicht mehr gepflegt. Das swagger-cli Repository auf GitHub erklärt unmissverständlich, dass es veraltet ist, und nennt als Grund „die Wartungslast, die entsteht, wenn man versucht, den Erwartungen einer riesigen Nutzerbasis mit wenig bis gar keinen Beiträgen gerecht zu werden.“ Die README selbst verweist auf Redocly CLI als Nachfolger.
Sie benötigen also einen Ersatz. Dies betrifft speziell das Terminal-Tool swagger-cli, das validate und bundle ausführt. Wenn Sie eigentlich den Swagger Editor, SwaggerHub oder die umfassendere Design-Suite meinen, lesen Sie stattdessen 7 Swagger-Alternativen, die auch Ihre API testen.
Schauen wir uns an, was swagger-cli geleistet hat, und gehen wir dann die ehrliche Auswahlliste dessen durch, was jetzt zu verwenden ist.
Was swagger-cli tatsächlich geleistet hat
Es lohnt sich, präzise zu sein, denn der richtige Ersatz hängt davon ab, was Sie verwendet haben.
swagger-cli hatte genau zwei Befehle:
# Eine Swagger 2.0 / OpenAPI 3.0 Definition gegen das Schema validieren und $refs überprüfen
swagger-cli validate openapi.yaml
# $ref-Zeiger folgen und eine Definition aus mehreren Dateien in einer Datei zusammenfassen
swagger-cli bundle openapi.yaml -o bundled.json
Der bundle-Befehl hatte eine kleine Reihe von Optionen: -o/--outfile zum Schreiben in eine Datei, -t/--type zur Auswahl von JSON oder YAML, -r/--dereference zum vollständigen Inline-Einbetten jedes $ref und -f/--format für die Einrückung.
Das war das gesamte Tool. Es validierte die Struktur und bündelte Spezifikationen aus mehreren Dateien. Es hat keine Style-Regeln gelintet, keine Dokumente generiert, keine Tests ausgeführt oder irgendetwas gemockt. Wenn Sie Behauptungen lesen, dass swagger-cli Ihre Spezifikation „gelintet“ hat, liegen diese falsch; es hat Ihre Definition nur gegen das OpenAPI-Schema überprüft und Referenzen aufgelöst. Beachten Sie diesen Umfang, da einige Alternativen weitaus mehr leisten und Sie dies vielleicht wünschen oder auch nicht.
Die engere Auswahl
Drei Tools decken fast jeden Grund ab, warum Sie zu swagger-cli greifen würden, plus ein paar erwähnenswerte Spezialisten. Hier ist die ehrliche Übersicht.
Redocly CLI: der offizielle Nachfolger und engster 1:1-Ersatz
Redocly CLI (@redocly/cli, Binärdatei redocly) ist Open Source und das Tool, auf das die README von swagger-cli selbst verweist. Redocly veröffentlicht sogar einen Migrationsleitfaden von swagger-cli. Wenn Ihr Ziel ein direkter Terminal-Validator und Bundler ist, beginnen Sie hier.
Installieren Sie es auf die gleiche Weise, wie Sie swagger-cli installiert haben:
npm install -g @redocly/cli@latest
# oder ohne Installation ausführen
npx @redocly/cli@latest lint openapi.yaml
Die Zuordnung ist klar. swagger-cli’s validate wird zu redocly lint, das Ihre Spezifikation prüft und konfigurierbare Stilregeln anwendet. swagger-cli’s bundle wird zu redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
Hier ist die Gegenüberstellung der bundle-Flag-Zuordnungen:
| swagger-cli | Redocly CLI | Zweck |
|---|---|---|
-o, --outfile |
--output (oder -o) |
In eine Datei schreiben |
-t, --type |
--ext (json, yaml, yml) |
Ausgabeformat |
-r, --dereference |
-d, --dereferenced |
Alle $refs vollständig inline einbetten |
Eine Sache, die man wissen sollte: redocly lint leistet standardmäßig mehr als swagger-cli’s validate. Es wendet ein Style-Guide-Regelwerk an, nicht nur eine Schemaüberprüfung. Wenn Sie die einfache strukturelle Validierung wünschen, die swagger-cli Ihnen geboten hat, konfigurieren Sie eine redocly.yaml nur mit der spec-Regel und führen Sie dann redocly lint openapi.yaml aus. Dieses Regelwerksverhalten ist Redoclys größte Stärke und kein Nachteil; deshalb mögen es Teams, die eine Terminal-native Governance wünschen. Sie können Regelwerke anpassen (minimal, recommended, recommended-strict, spec) oder eigene Regeln schreiben. Siehe das beste OpenAPI Linter-Setup, wie dies neben anderen Lintern passt.
Redocly CLI geht auch über die zwei Befehle von swagger-cli hinaus. Es kann eine einzelne Beschreibung in eine Struktur aus mehreren Dateien aufteilen (das Gegenteil von bundle), mehrere Dateien zusammenführen (experimentell) und eigenständige Redoc HTML-Dokumentationen erstellen:
redocly build-docs openapi.yaml -o docs.html
Was es nicht tut: API-Tests ausführen oder einen Mock-Server hosten. Es ist ein code-first, Terminal-natives Lint-/Bundle-/Dokumentations-Tool, und ein exzellentes dazu. Wenn das alles ist, was Sie benötigen, können Sie mit dem Lesen aufhören und noch heute migrieren.
Apidog: wenn Sie mehr als Validierung plus Bündelung wünschen
Hier ist die ehrliche Neubetrachtung. swagger-cli war ein statisches Skript, das Sie zum Validieren und Bündeln ausgeführt haben. Aber für die meisten Teams sind Validierung und Bündelung Mittel zum Zweck. Sie validieren, damit die Spezifikation korrekt ist, Sie bündeln, damit sie portabel ist, und dann mocken, testen und dokumentieren Sie sie. swagger-cli hat diese späteren Schritte an andere Tools delegiert.
Apidog schließt diese Lücke. Es ist eine All-in-One-API-Plattform: Design, Mock, Test und Docs in einem Arbeitsbereich, mit einem CLI, das Import, Export und CI-Testläufe handhabt. Wo swagger-cli Ihnen eine Datei gab, gibt Ihnen Apidog einen lebendigen Arbeitsbereich, der aus dieser Datei erstellt wurde.
Die beiden Befehle, die am direktesten Ihrer swagger-cli-Muskelgedächtnis entsprechen, sind import und export. Installieren Sie das CLI und authentifizieren Sie sich zuerst:
npm install -g apidog-cli@latest
apidog login --with-token <IHR_TOKEN>
Sie erhalten das Token aus der Apidog-App oder dem Web: Avatar, dann Kontoeinstellungen, dann API-Zugriffstoken. Es wird in ~/.apidog/config.toml gespeichert, drucken oder committen Sie es also niemals.
Import ist Ihr Validierungsschritt. Es nimmt eine Definition in ein Projekt auf und löst Multi-File-$refs in vereinheitlichte Ressourcen auf. Wenn die Datei fehlerhaft ist, zeigt der Import dies an:
apidog import --project 123456 --format openapi --file ./openapi.json
Der Import akzeptiert eine lange Liste von Formaten über OpenAPI hinaus, darunter Postman, HAR, Insomnia, WSDL und JSON Schema, was praktisch ist, wenn Ihre Quellen gemischt sind.
Export ist Ihr Bündelungsschritt, mit einem Bonus. Es gibt eine einzige konsolidierte Datei aus, und Sie wählen die OpenAPI-Version beim Export. Das macht es zu einem Bundle plus einem optionalen Spezifikations-Upgrade in einem Befehl:
# Bündeln und in einem Schritt auf OpenAPI 3.1 aktualisieren
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Oder eigenständige HTML-Dokumente ausgeben
apidog export --project 123456 --format html --output ./docs.html
Für CI fügt Apidog den Schritt hinzu, den swagger-cli nie hatte: Tests ausführen.
# Ein Testszenario in CI mit mehreren Berichtsformaten ausführen
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# Oder vollständig offline aus einer exportierten Sammlungsdatei ausführen
apidog run ./collection.apidog-cli.json
Das CLI verwaltet auch Projektressourcen direkt, einschließlich endpoint, schema, mock, environment, branch, test-suite und test-report. Für Einrichtungsdetails und alle Flags siehe den vollständigen Leitfaden für Apidog CLI und die offizielle Apidog CLI-Dokumentation.
Nun zu den ehrlichen Grenzen, denn Passung zählt mehr als Hype. Das CLI von Apidog validiert die Struktur beim Import, bietet aber keinen konfigurierbaren, code-first Style-Guide-Linter mit benutzerdefinierten Regelwerken, wie es Redoclys lint tut. Es gibt keinen apidog lint-Befehl, und Sie können keine benutzerdefinierten Regeln im Spectral-Stil über das CLI erstellen. Es gibt auch kein split oder join. Apidog ist GUI-first: Design, Mocking, visuelle Testerstellung und Dokumentation werden hauptsächlich in der Desktop- oder Web-App erstellt, wobei das CLI den Import, Export, CI-Testläufe und die Ressourcenverwaltung für ein Projekt übernimmt. Und Apidog ist Freemium, nicht Open Source, daher ist es ein anderes Modell als Redocly CLI und Spectral.
Spectral: reines, anpassbares Linting in CI
Wenn Sie von swagger-cli wirklich eine strenge, meinungsstarke Validierung in Ihrer Pipeline wollten, ist der dedizierte Linter Spectral von Stoplight. Es ist Open Source und für eine Aufgabe konzipiert: das Anwenden eines anpassbaren Regelwerks auf OpenAPI- (und andere JSON/YAML-) Dokumente.
Spectral glänzt, wenn Sie Ihren Hausstil als Code, mit Ihren eigenen Regeln, in jedem Pull Request durchsetzen möchten. Es bündelt nicht, generiert keine Dokumente und testet keine Endpunkte; es lintet. Kombinieren Sie es mit einem Bundler, und Sie haben eine fokussierte Version dessen, was swagger-cli geleistet hat, plus echte Governance, neu erstellt. Unser Leitfaden zu Spectral OpenAPI-Linting erklärt das Schreiben von Regelwerken, und die Validierung von OpenAPI in CI behandelt die Einbindung in eine Pipeline.
Kurz gesagt: openapi-generator und vacuum
Zwei weitere Tools tauchen auf, hier ist also die genaue, kurze Version. openapi-generator ist ein Code- und Client-Generator; wenn Ihr Grund für das Bündeln die Speisung eines Generators war, benötigen Sie möglicherweise überhaupt keinen separaten Bündelungsschritt, da er Spezifikationen direkt verarbeitet. vacuum ist ein schneller, Spectral-kompatibler OpenAPI-Linter, geschrieben in Go, eine gute Wahl, wenn die Lint-Geschwindigkeit in großen Monorepos wichtig ist. Keines davon ist für sich genommen ein allgemeiner Validate-plus-Bundle-Ersatz, aber beide erfüllen spezifische Bedürfnisse.
Vergleichstabelle
Hier ist, wie sich die Optionen hinsichtlich der Funktionen vergleichen lassen, die swagger-cli-Benutzer typischerweise interessieren.
| Tool | Validieren | Bündeln | Lint-Regeln | Dokumente | Mocken | Testen | Open Source | Am besten geeignet für |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | Ja | Ja | Nein | Nein | Nein | Nein | Ja (veraltet) | Nichts Neues; es wird nicht mehr gepflegt |
| Redocly CLI | Ja (lint) |
Ja | Ja (konfigurierbar) | Ja (Redoc HTML) | Nein | Nein | Ja | Ein direkter Terminal-Validate-/Bundle-Austausch mit Governance |
| Apidog | Ja (beim Import) | Ja (beim Export, mit OAS-Upgrade) | Nur strukturell, keine benutzerdefinierten Regelwerke | Ja (App + Export) | Ja | Ja (CLI-Ausführung) | Nein (Freemium) | Ein Tool für den gesamten API-Lebenszyklus |
| Spectral | Ja (Lint-basiert) | Nein | Ja (benutzerdefinierte Regelwerke) | Nein | Nein | Nein | Ja | Strenges, anpassbares Linting in CI |
| vacuum | Ja (Lint-basiert) | Nein | Ja (Spectral-kompatibel) | Nein | Nein | Nein | Ja | Schnelles Linting bei großen Spezifikationen |
Die Empfehlung
Dies ist keine „alles ist großartig, wähle deinen Favoriten“-Situation. Zwei klare Wege decken fast jeden ab.
Wählen Sie Redocly CLI, wenn Sie einen direkten Austausch wünschen. Es ist der offizielle Nachfolger, es ist Open Source, und die Migration ist nahezu mechanisch: validate zu lint, bundle zu bundle, mit der oben genannten Flag-Zuordnung. Wenn Ihr Workflow wirklich nur „Validieren und Bündeln vom Terminal aus“ ist und Sie später Governance-Regeln hinzufügen möchten, ohne die Tools zu wechseln, ist Redocly die offensichtliche Wahl. Es hält Sie Code-first und Terminal-nativ, genau dort, wo swagger-cli angesiedelt war.
Wählen Sie Apidog, wenn Validierung und Bündelung nur der Anfang waren. Die meisten Teams validieren eine Spezifikation nicht um ihrer selbst willen. Sie validieren sie, dann benötigt jemand einen Mock zum Aufbauen, jemand anderes schreibt Tests, und jemand ist für die Dokumentation zuständig. swagger-cli stoppte bei Schritt eins und zwang Sie, den Rest aus Spectral, einem Bundler, Postman und Newman zusammenzustellen. Apidog vereint Import (Validierung), Export (Bündelung plus ein OAS-Versions-Upgrade), Mock, Test und Dokumentation in einem Arbeitsbereich, mit einem CLI für die Teile, die in CI gehören. Sie hören auf, ein statisches, jetzt nicht mehr gepflegtes Skript zu betreuen, und bringen die gesamte Spezifikation an einen Ort, wo sie nach dem Bündeln nützlich bleibt.
Dies sind unterschiedliche Paradigmen, keine konkurrierenden Versionen desselben. Redocly CLI ist der leichte, konfigurierbare Spezialist, den Sie rein vom Terminal aus ausführen. Apidog ist die All-in-One-Plattform, die zufällig ein fähiges CLI besitzt. Wählen Sie basierend darauf, wie viel des Lebenszyklus Sie in einem Tool haben möchten, und seien Sie ehrlich dabei: Wenn Sie nur im Terminal linten und bündeln möchten, ist Redocly schlanker und kostenlos.
Wenn Sie den Lebenszyklus-Ansatz ausprobieren möchten, laden Sie Apidog herunter und importieren Sie eine bestehende Spezifikation; der Start ist kostenlos, keine Kreditkarte erforderlich, und Sie können Ihre gebündelte, versionierte Ausgabe in wenigen Minuten sehen.
Häufig gestellte Fragen
Wird swagger-cli noch gepflegt?
Nein. Das swagger-cli GitHub-Repository ist als veraltet und nicht mehr gepflegt gekennzeichnet, unter Berufung auf geringe Beiträge bei einer großen Benutzerbasis. Es lässt sich immer noch installieren und ausführen, aber es wird keine Fehlerbehebungen oder Updates erhalten, planen Sie also eine Migration.
Was hat swagger-cli ersetzt?
Die README des Projekts selbst verweist auf Redocly CLI als Nachfolger. redocly lint ersetzt swagger-cli validate und redocly bundle ersetzt swagger-cli bundle. Redocly veröffentlicht sogar einen dedizierten Migrationsleitfaden. Wenn Sie mehr als Validieren und Bündeln wünschen, deckt Apidog Import, Export, Mock, Test und Dokumentation an einem Ort ab.
Ist Apidog kostenlos?
Apidog ist Freemium. Es gibt eine kostenlose Stufe, mit der Sie ohne Kreditkarte beginnen können, mit kostenpflichtigen Plänen für größere Teams und erweiterte Anforderungen. Es ist nicht Open Source, was der Hauptunterschied zu Redocly CLI und Spectral ist, falls eine Open-Source-Lizenzierung eine Anforderung für Sie ist.
Kann ich meinen swagger-cli-Workflow genau so beibehalten?
Am nächsten kommt Redocly CLI. Um die einfache strukturelle Validierung von swagger-cli widerzuspiegeln, richten Sie eine redocly.yaml nur mit der spec-Regel ein und führen Sie redocly lint aus. Für das Bündeln lassen sich die Befehle und Flags fast eins zu eins zuordnen. Für einen tieferen Einblick in den Umfang des ursprünglichen Tools, siehe wie man swagger-cli vom Terminal aus verwendet.