DEV Community

Cover image for Kostenlose Open-Source CLI-Tools für API-Design
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

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

API-Design passiert in der Spezifikationsdatei – lange bevor Code ausgeliefert wird. Eine vergessene Stilregel, eine übersehene Breaking Change oder ein Schema, das von der letzten produktiven Version abweicht, ist später deutlich teurer zu beheben. Mit CLI-Tools prüfen Sie diese Probleme direkt im Repository, lokal und in CI, ohne manuelle Schritte in einer Benutzeroberfläche.

Apidog noch heute ausprobieren

Dieser Beitrag konzentriert sich auf die Open-Source-Seite der Toolchain. Jedes vorgestellte Tool ist unter einer permissiven Lizenz quelloffen, ohne Lizenzgebühren nutzbar und kann selbst gehostet oder auf eine feste Version gepinnt werden. Das ist wichtig, wenn Ihr API-Design in Git liegt und Prüfungen auf jedem Laptop sowie in jeder Pipeline identisch laufen sollen. Für den übergeordneten Prozess lesen Sie zuerst unseren Leitfaden zu wie man eine API entwirft und wählen Sie anschließend die passenden CLIs.

Sie erhalten sechs Tools mit konkreten Installations- und Beispielbefehlen:

  • Spectral für Stilregeln
  • vacuum als schnelle Go-basierte Alternative für Spectral-Regeln
  • Redocly CLI für Linting und Bundling
  • openapi-generator für Clients, Server-Stubs und Dokumentation
  • oasdiff und Optic zum Erkennen von Breaking Changes

Die OpenAPI Specification ist die gemeinsame Sprache dieser Tools. Eine Spezifikation, die Sie linten, bündeln und validieren, kann anschließend direkt für Codegenerierung und Diff-Prüfungen verwendet werden.

Hinweis zu Apidog: Apidog ist nicht Open Source und lintet Ihre Spezifikation nicht. Es ist ein kommerzielles Produkt mit kostenlosem Tarif und wird hier nur als integrierte Design- und Exportoption eingeordnet. Die folgenden Tools bilden die eigentliche Open-Source-Toolchain.

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

Für diese Liste muss ein Tool drei Kriterien erfüllen:

  1. Offene Lizenz

    Die Lizenz muss öffentlich einsehbar und tatsächlich Open Source sein, etwa MIT oder Apache-2.0. Damit können Sie das Tool ohne Sitzplatzlimits oder Lizenzgebühren in kommerziellen Projekten einsetzen.

  2. Self-Hosting und reproduzierbare Versionen

    Sie müssen eine Binärdatei oder ein Paket auf eine konkrete Version pinnen und vollständig offline ausführen können, beispielsweise in einem Air-Gapped-CI-Runner. Für die Kernfunktion darf kein Konto erforderlich sein.

  3. Aktive Wartung und Community

    Prüfen Sie aktuelle Commits, beantwortete Issues und ein öffentliches Changelog. Eine MIT-Lizenz allein reicht nicht aus, wenn ein Projekt nicht mehr gepflegt wird.

Spectral: flexibler OpenAPI-Stil-Linter

Spectral von Stoplight ist der Referenz-Linter für API-Beschreibungen und steht unter Apache-2.0. Das Tool liest Regeln aus YAML-, JSON- oder JavaScript-Dateien und prüft OpenAPI 3.x, OpenAPI 2.0, AsyncAPI und Arazzo.

Installation und erster Lauf:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral bringt einen oas-Regelsatz mit, der beispielsweise fehlende Beschreibungen, ungültige Beispiele und strukturelle Probleme meldet.

Der praktische Nutzen entsteht mit eigenen Regeln. Legen Sie diese als .spectral.yaml im Repository ab:

extends:
  - spectral:oas

rules:
  require-operation-id:
    description: Jede Operation benötigt eine operationId.
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  require-operation-description:
    description: Jede Operation benötigt eine Beschreibung.
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: description
      function: truthy
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie dann mit:

spectral lint openapi.yaml -r .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Am besten geeignet für: Team-Styleguides als ausführbare Regeln.

Einschränkung: Spectral prüft eine einzelne Spezifikation. Für Breaking Changes zwischen zwei Versionen benötigen Sie zusätzlich ein Diff-Tool wie oasdiff.

vacuum: schneller Linter für Spectral-Regelsätze

Wenn Spectral der Standard ist, bietet vacuum den Geschwindigkeitsvorteil. vacuum ist ein MIT-lizenzierter Go-Linter und mit Spectral-Regelsätzen kompatibel. Sie können daher bestehende Regeln weiterverwenden und große Spezifikationen schneller in Pre-Commit-Hooks oder CI prüfen.

Installation:

brew install --cask daveshanley/vacuum/vacuum
Enter fullscreen mode Exit fullscreen mode

Linting mit detaillierter Ausgabe:

vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie einen vorhandenen Spectral-Regelsatz:

vacuum lint -d -r .spectral.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

vacuum kann außerdem HTML-Berichte und Dokumentation aus derselben Spezifikation erzeugen. Da es als einzelne kompilierte Binärdatei ohne Node-Laufzeit läuft, startet es schnell und lässt sich einfach containerisieren.

Am besten geeignet für: Schnelles Linting großer Spezifikationen mit vorhandenen Spectral-Regeln.

Einschränkung: Das Regelsatz-Ökosystem und die Dokumentation orientieren sich weiterhin vor allem an Spectral. Schreiben Sie Regeln typischerweise für Spectral und führen Sie sie dann optional mit vacuum aus.

Redocly CLI: Linting und Bundling

Redocly CLI ist MIT-lizenziert und besonders nützlich für Spezifikationen mit vielen $ref-Dateien. Mit bundle führen Sie eine aufgeteilte Spezifikation wieder in eine einzelne Datei zusammen – ideal für Tools, die ein einzelnes OpenAPI-Dokument erwarten.

Installation:

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode

Linting und Bundling:

redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Eine wartbare Repository-Struktur könnte so aussehen:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas/
    │   ├── User.yaml
    │   └── Error.yaml
    └── responses/
        └── NotFound.yaml
Enter fullscreen mode Exit fullscreen mode

Das Aufteilen nach Ressourcen hält Diffs lesbar und reduziert Merge-Konflikte. Es ist ein Kernbestandteil eines Git-nativen API-Design-Workflows. redocly bundle erzeugt daraus wieder das Artefakt für CI, Mock-Server oder Dokumentationsseiten.

Am besten geeignet für: Multi-Datei-Spezifikationen mit $ref, die gebündelt und validiert werden müssen.

Einschränkung: Die Standard-Lint-Regeln sind weniger umfassend als ein vollständiger Spectral-Regelsatz. Viele Teams nutzen Redocly für Bundling und Spectral oder vacuum für strenge Stilregeln.

openapi-generator: Clients, Stubs und Dokumentation generieren

Design ist erst dann vollständig, wenn andere Teams darauf aufbauen können. openapi-generator steht unter Apache-2.0 und generiert Client-SDKs, Server-Stubs und Dokumentation aus OpenAPI-Spezifikationen.

Installation:

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Beispiel: TypeScript-Client mit Axios erzeugen:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Ersetzen Sie typescript-axios je nach Zielplattform, etwa durch:

openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

Führen Sie die Generierung bei jeder Spezifikationsänderung in CI aus. So bleiben SDKs und Vertrag synchron. Dieser schema-first-Ansatz ist zentral für vertragsgesteuerte APIs und wird auch in unseren API-Design-Prinzipien behandelt.

Am besten geeignet für: Generierte Clients, Server-Stubs und Dokumentation, die mit dem API-Vertrag synchron bleiben.

Einschränkung: Zum Ausführen ist JDK 11+ erforderlich. Generierter Code ist ein Ausgangspunkt und sollte vor dem Release geprüft werden; die Qualität variiert je nach Zielsprache und Generator.

oasdiff: Breaking Changes vor dem Merge erkennen

Ein Linter sagt Ihnen, ob eine Spezifikation strukturell und stilistisch sauber ist. Er erkennt jedoch nicht, ob eine umbenannte Property bestehende Clients beschädigt. oasdiff ist ein Apache-2.0-lizenziertes Go-Tool, das zwei Spezifikationsversionen vergleicht und Breaking Changes meldet.

Installation:

go install github.com/oasdiff/oasdiff@latest
Enter fullscreen mode Exit fullscreen mode

Breaking Changes prüfen:

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Weitere nützliche Befehle:

# Alle Änderungen als lesbares Changelog
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Vollständiger, maschinenlesbarer Diff
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Binden Sie oasdiff breaking in Pull-Request-Prüfungen ein:

oasdiff breaking main-openapi.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Damit wird eine inkompatible Änderung zu einem fehlgeschlagenen Build statt zu einem Produktionsproblem.

Am besten geeignet für: Breaking-Change-Prüfungen in CI.

Einschränkung: oasdiff vergleicht nur Spezifikationen. Ihre OpenAPI-Datei muss daher die reale API zuverlässig abbilden. Stilregeln prüfen Sie weiterhin mit Spectral oder vacuum.

Optic: Lint und Diff in einem Tool – mit Wartungshinweis

Optic ist MIT-lizenziert und kombiniert Linting mit OpenAPI-Diffs. Es kann zwei Spezifikationsversionen vergleichen, Breaking Changes markieren und Stilregeln anwenden. Außerdem konnte es Spezifikationen aus beobachtetem Testverkehr generieren.

Installation und Diff-Prüfung:

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

Wichtig für die Toolauswahl: Das öffentliche Optic-Repository wurde Anfang 2026 archiviert und wird nicht mehr aktiv gepflegt. Die MIT-lizenzierte Quelle ist weiterhin verfügbar, aber Sie erhalten keine neuen Regeln oder Sicherheitspatches.

Am besten geeignet für: Bestehende Optic-Pipelines oder Teams, die Lint und Diff in einer CLI benötigen.

Einschränkung: Seit Anfang 2026 nicht mehr gepflegt. Behandeln Sie Optic als veraltet und planen Sie mittelfristig eine Migration, etwa zu oasdiff für Breaking-Change-Prüfungen.

Wo Apidog passt – und wo nicht

Apidog ist nicht Open Source und lintet OpenAPI nicht. Für Stilregeln verwenden Sie Spectral, vacuum oder Redocly CLI.

Apidog deckt einen anderen Teil des Workflows ab: Sie können Endpunkte und Datenschemas in einem integrierten Tool entwerfen und anschließend als OpenAPI exportieren. Diese Exportdatei übergeben Sie dann an die Open-Source-Prüfungen.

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

Die CLI enthält Befehlsgruppen für endpoint, schema, mock und import/export. Dadurch können Sie Design-Aufgaben im Terminal automatisieren und die exportierte Spezifikation direkt an openapi-generator oder oasdiff weiterreichen.

Den vollständigen Befehlssatz finden Sie im vollständigen Apidog CLI-Handbuch.

Die korrekte Einordnung: Apidog ist eine kommerzielle, integrierte Option für Design und Export. Es ergänzt die Open-Source-Toolchain, ersetzt aber weder einen Linter noch ist es selbst ein Open-Source-Projekt.

So wählen Sie aus

Ordnen Sie jedes Tool einer klaren Aufgabe zu. In der Praxis verwenden die meisten Teams zwei bis vier Tools zusammen.

Tool Am besten für Installation Open Source? Hinweise
Spectral Styleguide-Linting npm i -g @stoplight/spectral-cli Ja (Apache-2.0) Referenz-Linter für benutzerdefinierte Regeln
vacuum Schnelles Linting im großen Maßstab brew install --cask daveshanley/vacuum/vacuum Ja (MIT) Führt Spectral-Regelsätze schnell aus
Redocly CLI Bundling und Validierung npm i -g @redocly/cli Ja (MIT) Besonders für Multi-Datei-$ref-Spezifikationen
openapi-generator SDK-, Stub- und Doku-Generierung npm i -g @openapitools/openapi-generator-cli Ja (Apache-2.0) Benötigt JDK 11+
oasdiff Breaking Changes erkennen go install github.com/oasdiff/oasdiff@latest Ja (Apache-2.0) Gepflegte Option für PR-Prüfungen
Optic Lint und Diff kombiniert npm i -g @useoptic/optic Ja (MIT) Repository Anfang 2026 archiviert
Apidog CLI Integriertes Design und OpenAPI-Export npm i -g apidog-cli Nein (kostenloser Tarif) Kein Linter; exportiert OpenAPI

Ein praxistauglicher Stack sieht so aus:

  1. Spectral oder vacuum prüft Stilregeln.
  2. Redocly CLI bündelt Multi-Datei-Spezifikationen.
  3. oasdiff blockiert Breaking Changes im Pull Request.
  4. openapi-generator aktualisiert Clients und Stubs.

Ein minimaler CI-Schritt könnte beispielsweise so aussehen:

# 1. Stil und Struktur prüfen
spectral lint openapi.yaml

# 2. Referenzen auflösen und ein Artefakt erzeugen
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. Kompatibilität zur Basisversion prüfen
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# 4. Client generieren
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Wenn Sie zusätzlich eine integrierte Oberfläche für das Design und einen OpenAPI-Export benötigen, kann Apidog diesen Teil übernehmen. Für einen breiteren Überblick jenseits der CLI lesen Sie unseren Leitfaden zu Swagger-Alternativen für API-Design und -Tests sowie die Grundlagen in wie man REST-APIs entwirft.

Zusammenfassung

Die Open-Source-CLI-Toolchain für API-Design ist ausgereift und ohne Lizenzgebühren nutzbar:

  • Spectral und vacuum prüfen Stil und Qualität.
  • Redocly CLI bündelt aufgeteilte Spezifikationen.
  • openapi-generator erzeugt Clients, Stubs und Dokumentation.
  • oasdiff schützt vor Breaking Changes.
  • Optic bleibt für bestehende Pipelines relevant, gilt aber als veraltet.

Binden Sie diese Schritte in CI ein. Dann wird Ihr API-Vertrag bei jedem Push geprüft – ohne Pro-Sitz-Kosten und ohne Vendor-Lock-in.

Wenn Sie Endpunkte und Schemas lieber in einem integrierten Tool entwerfen und anschließend saubere OpenAPI in dieselbe Pipeline exportieren möchten, laden Sie Apidog herunter und testen Sie die apidog-cli. Apidog ist der kommerzielle Begleiter des Open-Source-Stacks, kein Ersatz für Ihren Linter.

Top comments (0)