DEV Community

Cover image for Beste schlanke CLI-Tools für API-Design
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Beste schlanke CLI-Tools für API-Design

Die meisten API-Design-Aufgaben brauchen keine Desktop-App oder einen zusätzlichen Dienst: Benennungen prüfen, eine aufgeteilte Spezifikation bündeln oder Breaking Changes erkennen, lässt sich direkt im Terminal erledigen. Mit den richtigen CLIs wird daraus ein reproduzierbarer Workflow für lokale Entwicklung und CI.

Teste Apidog noch heute

Dieser Artikel zeigt sechs leichtgewichtige Tools mit konkreten Installations- und Beispielbefehlen: Linting, Bündelung, Code-Generierung, Breaking-Change-Checks sowie das Entwerfen und Exportieren von OpenAPI über die Apidog CLI. Die OpenAPI-Spezifikation ist dabei das gemeinsame Austauschformat. Für den übergeordneten Prozess empfiehlt sich zuerst der Leitfaden zum API-Design.

Was ein leichtgewichtiges CLI-Tool ausmacht

Ein Tool ist nicht wegen weniger Funktionen leichtgewichtig, sondern wegen geringer Reibung im täglichen Einsatz. Für API-Design-CLIs sind drei Kriterien entscheidend:

  1. Schneller Start: Eine Binärdatei oder ein npx-Aufruf ist ideal. Das Tool sollte auch in einem frischen CI-Container ohne lange Einrichtung laufen.
  2. Sinnvolle Standardwerte: Ein erster Check sollte ohne umfangreiche Konfiguration möglich sein. Teamregeln können danach ergänzt werden.
  3. Skriptfähigkeit: Klare Exit-Codes und strukturierte oder grepbare Ausgaben machen denselben Befehl lokal und im Pull Request nutzbar.

Die folgenden Tools sind ungefähr nach ihrem Footprint sortiert: von sofort nutzbaren npx-Befehlen bis zu Generatoren mit JVM-Abhängigkeit.

Redocly CLI: Spezifikationen linten und bündeln

Redocly CLI lässt sich ohne globale Installation verwenden. Das eignet sich für einmalige Prüfungen und CI-Jobs.

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Verwende lint, um strukturelle Probleme früh zu erkennen. Verwende bundle, wenn deine Spezifikation auf mehrere Dateien verteilt ist:

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

Der Bundle-Schritt löst $ref-Verweise auf und erzeugt ein einzelnes OpenAPI-Dokument. Das ist praktisch für Dokumentation, Mock-Server und Tools, die keine Multi-Datei-Spezifikationen verarbeiten. Die Aufteilung nach Ressourcen hält Diffs übersichtlich und reduziert Merge-Konflikte – ein zentraler Bestandteil eines Git-nativen API-Design-Workflows.

Geeignet für: Schnelles Linting und Bündeln von Multi-Datei-Spezifikationen.

Einschränkung: Die Standardregeln sind meist weniger strikt als ein eigener Team-Regelsatz. Kombiniere Redocly bei Bedarf mit Spectral.

Spectral: API-Styleguide als Code durchsetzen

Spectral von Stoplight ist ein Open-Source-Linter für OpenAPI-, AsyncAPI- und Arazzo-Dokumente. Ohne eigene Konfiguration nutzt Spectral integrierte OAS-Regeln.

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

Für verbindliche Teamregeln lege eine .spectral.yaml im Repository an:

extends:
  - spectral:oas

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

  path-kebab-case:
    description: Pfade müssen kebab-case verwenden.
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/([a-z0-9]+(-[a-z0-9]+)*/?)*$"
Enter fullscreen mode Exit fullscreen mode

Führe danach denselben Check lokal und in CI aus:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

So werden Regeln wie verpflichtende operationId-Werte, Fehler-Schemata oder Pfadkonventionen überprüfbar statt nur dokumentiert. Das unterstützt die Umsetzung klarer API-Designprinzipien.

Geeignet für: Durchsetzung eines API-Styleguides im Repository.

Einschränkung: Spectral vergleicht keine zwei API-Versionen. Für Breaking Changes brauchst du zusätzlich ein Diff-Tool.

oasdiff: Breaking Changes im Pull Request erkennen

Ein Linter prüft die Qualität einer einzelnen Spezifikation. Er erkennt jedoch nicht automatisch, ob ein entferntes Feld oder ein geänderter Endpunkt bestehende Clients bricht. oasdiff vergleicht zwei OpenAPI-Versionen und erkennt Breaking Changes.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Die wichtigsten Befehle:

# Nur Breaking Changes anzeigen
oasdiff breaking old-openapi.yaml new-openapi.yaml

# Menschlich lesbares Änderungsprotokoll erstellen
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Vollständigen maschinenlesbaren Diff erzeugen
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ein einfacher CI-Schritt kann den Merge blockieren, wenn sich der Vertrag inkompatibel ändert:

- name: Check breaking OpenAPI changes
  run: |
    oasdiff breaking main-openapi.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Geeignet für: Breaking-Change-Checks mit minimaler Einrichtung.

Einschränkung: oasdiff kann nur den dokumentierten Vertrag prüfen. Die OpenAPI-Spezifikation muss daher mit der tatsächlich ausgelieferten API synchron bleiben.

Optic: Linting und Diffing in einem Tool

Optic kombiniert OpenAPI-Linting und Versionsvergleiche. Der Kernbefehl ist kurz:

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

Für bestehende Pipelines kann das weiterhin relevant sein. Das öffentliche Repository wurde jedoch im Januar 2026 archiviert und das Projekt wird nicht mehr gewartet. Die MIT-lizenzierte Quelle ist weiterhin verfügbar, aber es sind keine neuen Regeln oder Sicherheitspatches zu erwarten.

Geeignet für: Bestehende Teams, die Optic bereits einsetzen.

Einschränkung: Als Legacy behandeln und eine Migration planen. Für neue Breaking-Change-Checks ist oasdiff die gepflegte, leichtere Option.

openapi-generator: Clients, Server-Stubs und Dokumentation erzeugen

openapi-generator erzeugt aus einer OpenAPI-Spezifikation Client-SDKs, Server-Stubs und Dokumentation. Es benötigt eine JVM, der CLI-Workflow bleibt aber einfach.

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

Wechsle den Generator mit -g, zum Beispiel:

# Go-Client
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Python-Client
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Java-Server-Stub
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server
Enter fullscreen mode Exit fullscreen mode

Führe die Generierung bei Spezifikationsänderungen in CI aus. So bleiben SDKs und Server-Stubs am API-Vertrag ausgerichtet:

openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
git diff --exit-code ./client
Enter fullscreen mode Exit fullscreen mode

Das entspricht dem Design-First-Prinzip: Die Spezifikation ist die Quelle der Wahrheit, abgeleitete Artefakte werden daraus erzeugt. Weitere Grundlagen dazu finden sich im Beitrag zur Design-First-API-Entwicklung.

Geeignet für: Client-SDKs, Server-Stubs und Dokumentation aus dem Vertrag erzeugen.

Einschränkung: Benötigt JDK 11 oder neuer. Der generierte Code ist ein Ausgangspunkt und sollte pro Sprache überprüft und gegebenenfalls angepasst werden.

Apidog CLI: Endpunkte und Schemata im Terminal entwerfen

Die bisherigen Tools prüfen oder transformieren vorhandene Spezifikationen. Apidog setzt davor an: Mit apidog-cli lassen sich Endpunkte und Datenmodelle über die Kommandozeile verwalten und anschließend als OpenAPI exportieren.

npm install -g apidog-cli

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

Die CLI bietet Befehlsgruppen für:

  • endpoint
  • schema
  • security-scheme
  • folder
  • mock
  • import
  • export

Ein möglicher Ablauf ist:

# Entwurf aus Apidog exportieren
apidog export --format openapi -o openapi.yaml

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

# Für nachgelagerte Tools bündeln
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# Gegen die vorherige Version prüfen
oasdiff breaking previous-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Die CLI liefert strukturiertes JSON mit agentHints.nextSteps, was sich für automatisierte Terminal-Workflows eignet. Den vollständigen Befehlssatz beschreibt der Apidog CLI-Leitfaden.

Geeignet für: Endpunkte und Schemata zentral entwerfen und als OpenAPI exportieren.

Einschränkung: Apidog lintet keine OpenAPI-Spezifikationen und erzwingt keine Stilregeln. Dafür bleiben Spectral und Redocly zuständig. Apidog ist nicht Open Source, bietet jedoch einen kostenlosen Tarif.

Auswahlhilfe

Tool Am besten geeignet für Installation Open Source? Anmerkungen
Redocly CLI Bündelung und schnelles Linting npx @redocly/cli@latest Ja (MIT) Keine Installation nötig; gut für Multi-Datei-Spezifikationen
Spectral Stilrichtlinien-Linting npm i -g @stoplight/spectral-cli Ja (Apache-2.0) Startet ohne Konfiguration; eigene Regeln im Repository
oasdiff Breaking Changes erkennen go install github.com/oasdiff/oasdiff@latest Ja (Apache-2.0) Einzelne Go-Binärdatei; gepflegt
Optic Linting und Diffing kombiniert npm i -g @useoptic/optic Ja (MIT) Repository seit Januar 2026 archiviert; Legacy
openapi-generator SDK-, Stub- und Dokumentationsgenerierung npm i -g @openapitools/openapi-generator-cli Ja (Apache-2.0) Benötigt JDK 11+
Apidog CLI Endpunkte entwerfen und OpenAPI exportieren npm i -g apidog-cli Nein (kostenloser Tarif) Kein Linter; exportiert OpenAPI für weitere Tools

Praktischer CI-Workflow

Für viele Teams reichen vier Schritte:

# 1. OpenAPI exportieren oder aus dem Repository verwenden
apidog export --format openapi -o openapi.yaml

# 2. Teamregeln prüfen
spectral lint openapi.yaml

# 3. Referenzen auflösen und ein Artefakt erzeugen
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# 4. Inkompatible Änderungen blockieren
oasdiff breaking previous-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Wenn du SDKs benötigst, ergänze die Generierung:

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

Für einen breiteren Überblick außerhalb der CLI-Welt siehe die Swagger-Alternativen für API-Design und -Tests sowie die Grundlagen zum Design von REST-APIs.

Zusammenfassung

Eine schlanke API-Design-Toolkette lässt sich direkt in Pull Requests und CI ausführen:

  • Redocly CLI bündelt und lintet Spezifikationen.
  • Spectral setzt Teamregeln und Namenskonventionen durch.
  • oasdiff erkennt Breaking Changes vor dem Merge.
  • openapi-generator erzeugt Clients, Stubs und Dokumentation.
  • Optic ist eine Legacy-Option für bestehende Pipelines.
  • Apidog CLI unterstützt den Entwurf und Export von Endpunkten und Schemata.

Wenn du Endpunkte und Datenmodelle zentral entwerfen und anschließend OpenAPI in diese Pipeline exportieren möchtest, kannst du Apidog herunterladen und apidog-cli ausprobieren. Es ergänzt Linter und Diff-Tools, ersetzt sie aber nicht.

Top comments (0)