DEV Community

Cover image for APIs über die Kommandozeile dokumentieren
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

APIs über die Kommandozeile dokumentieren

API-Dokumentationen veralten, sobald jemand eine Spezifikation ändert und die Referenz nicht neu generiert. Behandeln Sie die Dokumentation deshalb wie ein Build-Artefakt: Ein reproduzierbarer CLI-Befehl erzeugt sie lokal und in CI bei jedem Merge oder Push.

Apidog heute ausprobieren

CLI-Workflows sind skriptfähig, erzeugen überprüfbare Diffs und lassen sich von CI-Runnern oder Agenten ausführen. Kein manueller Export im Browser und kein vergessener Klick auf „Exportieren“.

Dieser Leitfaden zeigt drei praktische Wege:

  1. Eine OpenAPI-Datei als eigenständige HTML-Referenz erzeugen.
  2. Eine OpenAPI-Datei nach Markdown konvertieren.
  3. Mit der Apidog CLI aus einem Live-Projekt exportieren und in CI automatisieren.

Für Hintergrund zu verfügbaren Optionen siehe auch die Übersicht der Top 10 Tools für die REST-API-Dokumentation sowie der kostenlosen API-Dokumentationstools.

Voraussetzungen

Sie benötigen eine API-Beschreibung, typischerweise als:

  • openapi.yaml
  • openapi.json

Die folgenden Tools arbeiten mit OpenAPI 3.x. Redocly unterstützt außerdem Swagger 2.0.

HTML-Referenz mit Redocly CLI erstellen

Die Redocly CLI erzeugt aus einer OpenAPI-Beschreibung eine eigenständige HTML-Datei. Das Ergebnis enthält Styles, Skripte und API-Referenz in einer Datei und kann direkt statisch gehostet werden.

1. CLI installieren

Global installieren:

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

Oder ohne globale Installation mit npx ausführen:

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

2. HTML generieren 

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Standardmäßig entsteht im aktuellen Verzeichnis:

redoc-static.html
Enter fullscreen mode Exit fullscreen mode

3. Zielpfad festlegen

Für eine typische statische Dokumentationsseite:

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie das Ergebnis lokal:

open docs/index.html
Enter fullscreen mode Exit fullscreen mode

Unter Linux können Sie alternativ einen einfachen lokalen Server starten:

python3 -m http.server --directory docs 8080
Enter fullscreen mode Exit fullscreen mode

Öffnen Sie anschließend http://localhost:8080.

Wann Redocly CLI sinnvoll ist: Sie benötigen schnell eine portable, eigenständige API-Referenz als HTML.

Einschränkung: build-docs erzeugt eine Referenzseite. Umfangreichere Inhalte wie Tutorials, Migrationsleitfäden oder Einstiegsseiten müssen Sie separat verwalten.

Markdown mit Widdershins generieren

Wenn Ihre Dokumentation in einem Repository, einem Static-Site-Generator oder einem Markdown-basierten Wiki lebt, ist Markdown oft das passendere Ausgabeformat.

Widdershins konvertiert OpenAPI-, Swagger- und AsyncAPI-Definitionen in Slate-kompatibles Markdown.

1. Widdershins installieren 

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

2. OpenAPI nach Markdown konvertieren 

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

Danach können Sie die Datei direkt in Ihr Repository übernehmen:

mv api.md docs/api-reference.md
Enter fullscreen mode Exit fullscreen mode

3. Ausgabe in eine Pipeline leiten

Ohne -o schreibt Widdershins nach stdout. Das eignet sich für Shell-Pipelines:

widdershins openapi.yaml > docs/api-reference.md
Enter fullscreen mode Exit fullscreen mode

4. Sprach-Tabs für Beispiele konfigurieren 

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o docs/api-reference.md
Enter fullscreen mode Exit fullscreen mode

Wann Widdershins sinnvoll ist: Ihre bestehende Dokumentationspipeline basiert auf Markdown.

Für einen umfassenderen Workflow siehe den Leitfaden zu einem API-Dokumentationsgenerator mit Markdown-Export.

Wichtig: Redocly und Widdershins lesen nur die lokale Datei. Wenn openapi.yaml nicht aktuell ist, generieren Sie zuverlässig eine veraltete Dokumentation.

Aus einem Live-Projekt mit der Apidog CLI exportieren

Wenn Ihr Team API-Endpunkte, Schemas und Dokumentationsinhalte in einem zentralen Projekt pflegt, ist ein Export aus diesem Projekt robuster als ein Export von einer lokalen Datei.

Die kostenlose Stufe von Apidog und apidog-cli ermöglichen einen CLI-basierten Workflow: Das Team bearbeitet ein Projekt, die CLI exportiert daraus Referenz und Dokumentation.

1. Apidog CLI installieren 

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Falls Sie die lokale Umgebung erst einrichten müssen, hilft der Apidog CLI-Installationsleitfaden bei Node-Versionen und PATH-Konfiguration.

2. Mit einem Zugriffstoken anmelden 

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Das Token wird lokal gespeichert. In CI müssen Sie den Login jedoch in jedem frischen Runner erneut ausführen.

3. Verfügbare Optionen prüfen

Bevor Sie einen Befehl automatisieren, prüfen Sie die Flags Ihrer installierten Version:

apidog --help
apidog export --help
Enter fullscreen mode Exit fullscreen mode

Eine bestehende Spezifikation importieren

Wenn Ihre API aktuell als OpenAPI-Datei vorliegt, importieren Sie sie zuerst in ein Projekt:

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Je nach Eingabe können Sie auch andere unterstützte Formate importieren, darunter:

  • OpenAPI 3.x
  • Swagger 2.0
  • Postman
  • Apidog-Export

Nach dem Import dient das Projekt als zentrale Quelle für spätere Exporte.

Menschenlesbare Dokumentation exportieren

Mit apidog export können Sie unter anderem OpenAPI, HTML, Markdown oder Postman exportieren.

Markdown exportieren 

apidog export --project <projectId> \
  --format markdown \
  --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie anschließend den Git-Diff:

git diff -- docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

HTML exportieren 

apidog export --project <projectId> \
  --format html \
  --output ./docs/api-docs.html
Enter fullscreen mode Exit fullscreen mode

OpenAPI exportieren

Wenn nachgelagerte Tools eine portable Spezifikation benötigen:

apidog export --project <projectId> \
  --format openapi \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Wenn ein Projekt mehrere Services enthält, prüfen Sie die verfügbaren Umfangs- und ID-Flags in Ihrer Version:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Damit können Sie beispielsweise pro Service eine eigene Dokumentationsdatei erzeugen.

Schriftliche Anleitungen über die CLI verwalten

Eine API-Referenz beschreibt Endpunkte und Schemas. Vollständige Entwicklerdokumentation benötigt zusätzlich Inhalte wie:

  • Erste-Schritte-Anleitungen
  • Authentifizierungs-Workflows
  • Migrationshinweise
  • Fehlerbehandlung
  • Codebeispiele

In Apidog liegen solche Inhalte als Markdown-Dokumente im Dokumentenbaum des Projekts. Die CLI verwaltet sie über die Befehlsgruppe doc.

Starten Sie mit der Hilfe und listen Sie vorhandene Dokumente auf:

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Die CLI liefert JSON-Ergebnisse. Folgen Sie bei automatisierten Workflows den zurückgegebenen agentHints.nextSteps.

Wenn ein Befehl eine JSON-Nutzlast erwartet, kann die CLI das erwartete Schema ausgeben und Eingabedateien vor dem Senden validieren. Prüfen Sie dafür:

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

So erkennen Sie fehlende Felder lokal, bevor ein CI-Job oder API-Aufruf fehlschlägt.

Dokumentationsseite veröffentlichen

Neben einzelnen Markdown-Dokumenten können Sie auch veröffentlichte Dokumentationsseiten und teilbare Links über die CLI verwalten.

Prüfen Sie zunächst die verfügbaren Befehle:

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

Die Begriffe haben unterschiedliche Bedeutungen:

Befehl Zweck
doc Markdown-Dokument im API-Dokumentenbaum
docs-site Gehostete öffentliche Dokumentationsseite
shared-doc Teilbarer Dokumentationslink

Verwenden Sie docs-site, wenn Sie eine öffentliche Dokumentationsseite per Terminal konfigurieren oder aktualisieren möchten. Verwenden Sie shared-doc, wenn Sie gezielt einen Link für Partner oder interne Stakeholder bereitstellen möchten.

Der entscheidende Vorteil: Veröffentlichung wird ein reproduzierbarer Deployment-Schritt. Nach einer API-Änderung aktualisieren oder importieren Sie das Projekt und führen anschließend den passenden Veröffentlichungsbefehl erneut aus.

Dokumentation in GitHub Actions automatisieren

Sobald ein Export lokal funktioniert, gehört er in CI. Das folgende Beispiel generiert die Markdown-Referenz bei jedem Workflow-Lauf neu:

- name: API-Dokumente neu generieren
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

Ergänzen Sie anschließend einen Schritt, der Änderungen committet oder als Artefakt bereitstellt, abhängig von Ihrer Repository-Strategie.

Für Redocly oder Widdershins bleibt die Struktur identisch. Sie ersetzen nur den Export-Befehl:

- name: HTML-Referenz mit Redocly erzeugen
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Oder für Markdown mit Widdershins:

- name: Markdown-Referenz mit Widdershins erzeugen
  run: |
    npm install -g widdershins
    widdershins openapi.yaml -o docs/api-reference.md
Enter fullscreen mode Exit fullscreen mode

Eine vollständige Befehlsübersicht finden Sie im vollständigen Leitfaden zur Apidog CLI.

Häufige Fallstricke

Falsche oder fehlende Projekt-ID

Jeder Apidog-Aufruf für export, doc oder docs-site benötigt:

--project <projectId>
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie die technische Projekt-ID aus den Projekteinstellungen, nicht den lesbaren Projektnamen.

Token fehlt in CI

apidog login speichert das Token auf der Maschine, auf der der Befehl läuft. Ein CI-Runner startet normalerweise ohne gespeicherte Zugangsdaten.

Führen Sie deshalb im gleichen Job aus:

apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Speichern Sie Tokens ausschließlich als CI-Secret und niemals direkt in der Workflow-Datei.

Veraltete OpenAPI-Datei

Redocly und Widdershins generieren nur so aktuelle Dokumentation wie die Eingabedatei:

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Wenn openapi.yaml veraltet ist, ist auch die erzeugte Referenz veraltet. Stellen Sie deshalb sicher, dass die Datei vor dem Generieren aktualisiert wird, oder exportieren Sie aus einem zentral gepflegten Projekt.

Flags raten statt --help verwenden

Die Flags für export, doc, docs-site und shared-doc können je nach CLI-Version abweichen.

Prüfen Sie vor der Automatisierung:

apidog <command> --help
Enter fullscreen mode Exit fullscreen mode

Das dauert wenige Sekunden und verhindert fehlgeschlagene Builds durch nicht vorhandene oder geänderte Optionen.

Zusammenfassung

Wählen Sie das Ausgabeformat passend zu Ihrer Pipeline:

  • Redocly CLI für eine eigenständige HTML-Referenz.
  • Widdershins für Markdown in Repository- oder Static-Site-Workflows.
  • Apidog CLI für Exporte aus einem zentralen Live-Projekt sowie für Referenz, schriftliche Anleitungen und veröffentlichte Dokumentation.

Der wichtigste Schritt ist nicht das konkrete Tool, sondern die Automatisierung: Machen Sie den Dokumentationsexport zu einem CI-Schritt. Dann wird die Dokumentation bei Änderungen reproduzierbar neu erstellt, statt manuell nachgezogen werden zu müssen.

Laden Sie Apidog herunter, um die CLI auszuprobieren, oder erfahren Sie mehr darüber, wie Apidog in einen API-First-Workflow passt.

Top comments (0)