Kostenlose Open-Source CLI-Tools für API-Design

API-Design findet in Ihrer Spezifikationsdatei statt, lange bevor Code ausgeliefert wird. Eine vergessene Stilregel, eine übersehene Breaking Change, ein Schema, das von dem abweicht, was Sie letzte Woche ausgeliefert haben; all das ist im Nachhinein teurer zu beheben. Die Befehlszeile fängt diese Probleme dort ab, wo sie entstehen, und das in CI, ohne dass jemand durch eine Benutzeroberfläche klicken muss.

Dieser Beitrag handelt von der Open-Source-Seite dieser Toolchain. Jedes hier vorgestellte Tool ist unter einer permissiven Lizenz quelloffen, kostenlos ohne Lizenzgebühren nutzbar und kann selbst gehostet oder auf eine von Ihnen kontrollierte Version festgelegt werden. Das ist wichtig, wenn Ihr API-Design in einem Git-Repository liegt und Sie möchten, dass die Überprüfungen auf jedem Laptop und in jeder Pipeline auf die gleiche Weise ausgeführt werden. Wenn Sie ein umfassenderes Bild davon wünschen, wie diese zusammenpassen, beginnen Sie mit unserem Leitfaden zu wie man eine API entwirft, und kommen Sie dann hierher zurück, um die CLIs auszuwählen.

Sie erhalten sechs Tools, jedes mit einem echten Installationsbefehl und dem einen Befehl, der dessen Funktion zeigt: einen Linter für Stilregeln, eine schnelle Go-basierte Alternative dazu, einen Bundler, der auch validiert, einen Code- und Doku-Generator und zwei Tools zum Erkennen von Breaking Changes zwischen Spezifikationsversionen. Die OpenAPI Specification ist die gemeinsame Sprache, die alle sprechen, sodass eine Spezifikation, die Sie mit einem Tool linten, sauber in das nächste übergeht.

Eine ehrliche Anmerkung vorweg. Apidog wird hier vorgestellt, ist aber nicht Open Source; es ist ein kommerzielles Produkt mit einem kostenlosen Tarif und liniert Ihre Spezifikation nicht. Daher erhält es eine zutreffende Randbemerkung, keinen Open-Source-Eintrag. Die unten aufgeführten Tools sind die echte Open-Source-Design-Toolchain.

Was ein CLI-Tool für API-Design Open Source macht

Open Source ist eine spezifische Behauptung, keine Stimmung. Für diese Liste qualifiziert sich ein Tool, wenn drei Dinge zutreffen.

Erstens, die Lizenz. Es muss eine echte permissive oder Copyleft-Lizenz sein, die Sie lesen können; MIT und Apache-2.0 sind die beiden, die Sie hier am häufigsten sehen werden. Das ermöglicht es Ihnen, das Tool in einem kommerziellen Projekt ohne Lizenzgebühren oder Sitzplatzbeschränkungen zu verwenden.

Zweitens, Self-Hosting und Versionskontrolle. Sie können die Binärdatei einbinden, eine genaue Version festlegen und sie vollständig offline in einem Air-Gapped CI-Runner ausführen. Kein Tool hier sendet Daten nach Hause oder benötigt ein Konto, um seine Kernaufgabe zu erfüllen.

Drittens, Wartung und Community. Ein Repository mit aktuellen Commits, offenen Issues, die beantwortet werden, und einem öffentlichen Changelog. Ein aufgegebenes Projekt kann immer noch MIT-lizenziert sein und trotzdem eine schlechte Wahl sein, daher kennzeichne ich den Wartungsstatus, wo es darauf ankommt.

Jedes der unten aufgeführten Tools wird anhand dieser drei Punkte geprüft. Wo ein Projekt nur noch vor sich hin dümpelt, wird dies erwähnt.

Spectral: der flexible OpenAPI-Stil-Linter

Spectral von Stoplight ist der Referenz-Open-Source-Linter für API-Beschreibungen, lizenziert unter Apache-2.0. Er liest einen Regelsatz (eine YAML-, JSON- oder JavaScript-Datei, die Ihre Regeln auflistet) und wendet ihn auf OpenAPI 3.x, OpenAPI 2.0, AsyncAPI und Arazzo-Dokumente an. Wenn Ihr Team einen schriftlichen API-Styleguide hat, ist Spectral der Weg, diesen ausführbar zu machen.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Direkt nach der Installation wird ein oas-Regelsatz mitgeliefert, der fehlende Beschreibungen, ungültige Beispiele und strukturelle Probleme kennzeichnet. Der wahre Wert zeigt sich in benutzerdefinierten Regeln: eine operationId für jede Operation vorschreiben, ein geteiltes Schema für Fehlerantworten, eine Namenskonvention für Pfade. Diese Regeln leben in Ihrem Repository und werden für jeden Mitwirkenden identisch ausgeführt.

Am besten geeignet für: die Durchsetzung eines Team-Styleguides als Code. Ehrliche Einschränkung: Spectral prüft eine einzelne Spezifikation; es vergleicht keine zwei Versionen, daher kombinieren Sie es mit einem Diff-Tool, um Breaking Changes zu erkennen.

vacuum: der schnellste Linter, Drop-in für Spectral-Regelsätze

Wenn Spectral der Standard ist, ist vacuum der Geschwindigkeitsvorteil. Es ist ein Go-Linter, MIT-lizenziert, der zu 100% mit Spectral-Regelsätzen kompatibel ist. So können Sie es auf denselben Regelsatz richten, den Sie bereits geschrieben haben, und erhalten viel schnellere Ergebnisse bei großen Spezifikationen, was genau das ist, was Sie in einem Pre-Commit-Hook oder einer engen CI-Schleife wünschen.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

Der -d-Flag liefert Ihnen eine detaillierte Ausgabe pro Regel. vacuum liniert auch nicht nur; es generiert HTML-Berichte und Dokumentation aus derselben Spezifikation. Da es sich um eine einzelne kompilierte Binärdatei ohne Node-Laufzeit handelt, startet es schnell und lässt sich sauber in einen Container integrieren.

Am besten geeignet für: schnelles Linting großer Spezifikationen mit bereits vorhandenen Regelsätzen. Ehrliche Einschränkung: Das Regelsatz-Ökosystem und die Dokumentation konzentrieren sich immer noch auf Spectral, sodass Sie oft Regeln gegen Spectrals Modell schreiben und sie dann mit vacuum ausführen. Das ist zwar ein Feature, bedeutet aber, dass Spectral immer noch das ist, was man zuerst lernt.

Redocly CLI: Linting plus Bundling in einer Binärdatei

Redocly CLI ist MIT-lizenziert und deckt eine etwas andere Aufgabe ab. Es liniert, aber sein herausragendes Merkmal ist bundle: Es nimmt eine Spezifikation, die über viele $ref-Dateien verteilt ist (der vernünftige Weg, ein großes API-Design wartbar zu halten), und fasst sie in einem einzigen Dokument für Tools zusammen, die eine einzelne Datei erwarten. Es generiert auch API-Referenzdokumente aus dem gebündelten Ergebnis.

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

Das Aufteilen Ihrer Spezifikation in ressourcenspezifische Dateien hält Diffs lesbar und Merge-Konflikte klein, was ein Kernstück eines Git-nativen API-Design-Workflows ist. Redoclys bundle ist der Schritt, der diese Multi-Dateien-Quelle wieder in das einzelne Artefakt umwandelt, das Ihre CI, Ihr Mock-Server oder Ihre Dokumentationsseite konsumiert.

Am besten geeignet für: Multi-Datei-Spezifikationsprojekte, die Bundling plus einen Validierungsdurchlauf benötigen. Ehrliche Einschränkung: Seine Standard-Lint-Regeln sind leichter als ein vollständiger benutzerdefinierter Spectral-Regelsatz, daher verwenden viele Teams Redocly für das Bundling und Spectral oder vacuum für eine tiefgreifende Stil-Durchsetzung.

openapi-generator: das Design in Clients, Stubs und Dokumente umwandeln

Design ist erst abgeschlossen, wenn andere darauf aufbauen können. openapi-generator ist Apache-2.0 und generiert Client-SDKs, Server-Stubs und Dokumentation aus einer OpenAPI-Spezifikation in Dutzenden von Sprachen. Die Spezifikation als einzige Quelle der Wahrheit zu betrachten und den Rest zu generieren, ist das Herzstück eines schema-first, vertragsgesteuerten Ansatzes, den wir in API-Design-Prinzipien behandeln.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

Ersetzen Sie -g typescript-axios durch go, python, java, kotlin oder einen der vielen unterstützten Generatoren. Führen Sie es in CI bei jeder Spezifikationsänderung aus, und Ihre Client-Bibliotheken weichen niemals vom Vertrag ab.

Am besten geeignet für: die Synchronisierung von generiertem Code und Dokumenten mit dem Design. Ehrliche Einschränkung: Es benötigt ein JDK zum Ausführen (JDK 11+), der generierte Code ist ein Ausgangspunkt, den Sie oft anpassen werden, und die Qualität des Generators variiert je nach Zielsprache. Überprüfen Sie die Ausgabe, bevor Sie sie ausliefern.

oasdiff: Breaking Changes erkennen, bevor sie Clients erreichen

Ein Linter sagt Ihnen, ob eine Spezifikation sauber ist. Er kann Ihnen nicht sagen, dass die Umbenennung eines Feldes gerade jeden Client in der Produktion lahmgelegt hat. oasdiff ist das Apache-2.0 Go-Tool, das diese Lücke füllt: Geben Sie ihm zwei Versionen einer Spezifikation, und es meldet den Diff, und speziell die Breaking Changes.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

Der breaking-Befehl zeigt nur die Änderungen auf, die bestehende Konsumenten beeinträchtigen; changelog liefert eine menschenlesbare Liste aller Änderungen, ob Breaking Change oder nicht; diff liefert das vollständige maschinenlesbare Delta. Binden Sie oasdiff breaking in eine Pull-Request-Überprüfung ein, und eine Breaking Change wird zu einem fehlgeschlagenen Build anstelle einer Benachrichtigung um 3 Uhr morgens.

Am besten geeignet für: die Kontrolle von Breaking Changes in CI. Ehrliche Einschränkung: Es vergleicht Spezifikationen, daher ist es nur so gut wie Ihre Disziplin, die Spezifikation mit der realen API aktuell zu halten. Es liniert keinen Stil; verwenden Sie es zusammen mit Spectral oder vacuum.

Optic: Diff und Lint zusammen, mit einem Wartungshinweis

Optic ist MIT-lizenziert und tut etwas, das andere aufteilen: Es liniert und differenziert OpenAPI in einem Tool, vergleicht zwei Versionen, um Breaking Changes zu kennzeichnen, während es auch Stilregeln anwendet. Es könnte sogar eine Spezifikation aus beobachtetem Testverkehr generieren.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

Hier ist die Ehrlichkeit, die Ihnen eine Open-Source-Liste schuldet: Optic’s öffentliches Repository wurde Anfang 2026 archiviert und das Projekt wird nicht mehr aktiv gewartet. Die MIT-Quelle läuft immer noch, sodass Sie sie einbinden können, aber Sie erhalten keine neuen Regeln oder Sicherheitspatches. Für die Erkennung von Breaking Changes ist heute oasdiff die gepflegte Option; Optic bleibt auf der Liste, weil Sie es immer noch in bestehenden Pipelines finden werden.

Am besten geeignet für: Teams, die bereits darin investiert haben, oder alle, die Lint und Diff in einem CLI wünschen. Ehrliche Einschränkung: Wird seit Anfang 2026 nicht mehr gewartet; behandeln Sie es als veraltet und planen Sie einen Migrationspfad.

Wo Apidog passt (und wo nicht)

Apidog ist nicht Open Source und liniert weder Ihr OpenAPI noch erzwingt es Stilregeln; Spectral, vacuum und Redocly sind Ihre Linter, Punkt. Was Apidog bietet, ist ein anderer Kompromiss: Anstatt sechs separate Binärdateien zusammenzufügen, bietet Ihnen der kostenlose Tarif plus die apidog-cli-Binärdatei einen integrierten Ort zum Entwerfen von Endpunkten und Datenschemas und anschließend zum Exportieren des Ergebnisses als OpenAPI, um es direkt in diese Open-Source-Überprüfungen einzuspeisen.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

Die CLI verfügt über Befehlsgruppen für endpoint, schema, mock und import/export, sodass Sie API-Design vom Terminal aus skripten und die exportierte Spezifikation an openapi-generator oder oasdiff übergeben können. Den vollständigen Befehlssatz finden Sie im vollständigen Apidog CLI-Handbuch. Die ehrliche Einordnung: Apidog ist die kommerzielle, integrierte Option, die gut mit der Open-Source-Toolchain zusammenarbeitet, kein Ersatz für einen Linter und kein Open-Source-Projekt selbst.

So wählen Sie aus

Passen Sie das Tool der Aufgabe an. Die meisten Teams verwenden zwei oder drei davon zusammen, nicht nur eines.

Ein praktischer Stack: Spectral oder vacuum für den Stil, Redocly für das Bundling, oasdiff für Breaking Changes und openapi-generator zum Erstellen von Clients. Wenn die Wartung so vieler Tools mehr ist, als Sie möchten, deckt eine integrierte Plattform den Design- und Exportteil an einem Ort ab. Für einen breiteren Überblick über die Tool-Landschaft jenseits der CLI, lesen Sie unseren Leitfaden zu Swagger-Alternativen für API-Design und -Tests und die Grundlagen in wie man REST-APIs entwirft.

Zusammenfassung

Die Open-Source-CLI-Toolchain für API-Design ist ausgereift und kostenlos nutzbar: Spectral und vacuum linten, Redocly bündelt, openapi-generator erstellt Clients und oasdiff schützt vor Breaking Changes, wobei Optic als veraltete Option zu beachten ist. Binden Sie sie in CI ein, und Ihr API-Vertrag wird bei jedem Push überprüft, ohne Pro-Sitz-Kosten und ohne Vendor-Lock-in.

Wenn Sie Endpunkte und Schemas lieber in einem integrierten Tool entwerfen und saubere OpenAPI in dieselbe Pipeline exportieren möchten, laden Sie Apidog herunter und probieren Sie die apidog-cli aus; sie ist der kommerzielle Begleiter des Open-Source-Stacks, kein Ersatz für Ihren Linter. So oder so ist das Ziel dasselbe: Designprobleme im Terminal erkennen, bevor sie Ihre Benutzer erreichen.