Beste leichtgewichtige CLI-Tools für API-Dokumentation

Sie haben eine OpenAPI-Datei und möchten daraus Dokumentation erzeugen – ohne Dienst einzurichten, sich bei einem Portal anzumelden oder einen schweren Build-Schritt hinzuzufügen. Ziel ist ein einzelner Befehl: Spezifikation einlesen, Markdown-Datei oder eigenständige HTML-Seite erzeugen und die Ausgabe in Git, CI oder auf einem statischen Host verwenden.

Apidog noch heute ausprobieren

Diese Tools sind dafür ausgelegt: einzelne Binärdateien, npx-Befehle oder kleine Pakete. Einige erzeugen Markdown für bestehende Dokumentationsseiten, andere liefern direkt eine statische HTML-Datei. Alle lassen sich im Terminal und in CI verwenden.

Wenn Sie auch GUI-basierte Plattformen vergleichen möchten, finden Sie in dieser Übersicht der Top 10 REST-API-Dokumentationstools weitere Optionen. Die technische Grundlage bleibt die OpenAPI-Spezifikation: Sie definiert, welche Inhalte die folgenden Generatoren aus Ihrer Datei lesen können.

Was ein leichtgewichtiges CLI-Tool für API-Dokumentation ausmacht

Leichtgewichtig bedeutet nicht eingeschränkt. Entscheidend sind Installationsaufwand, Konfiguration und die Fähigkeit, zuverlässig in einer Pipeline zu laufen.

• Kleine Installation: Eine Binärdatei oder ein npm-Paket ist einfacher als eine vollständige Plattform mit Laufzeit, Bundler und Plugins.
• Direkter Start: Idealerweise genügt tool openapi.yaml, um eine Dokumentationsdatei zu erzeugen.
• Klare Ausgabe: Die Tools erzeugen Markdown oder HTML – ohne Serverbetrieb oder zusätzliche Infrastruktur.
• CI-tauglich: Sie funktionieren lokal genauso wie in GitHub Actions, GitLab CI oder jedem anderen CI-Job.

Eine breitere Auswahl finden Sie in der Übersicht der kostenlosen API-Dokumentationstools. Hier konzentrieren wir uns auf den terminalbasierten Workflow.

Widdershins: OpenAPI schnell in Markdown umwandeln

Widdershins konvertiert OpenAPI-3-, Swagger-2- und AsyncAPI-Dateien in Markdown. Es rendert keine Website und startet keinen Server – es erzeugt einfach eine .md-Datei.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

Für einen einmaligen Lauf ohne globale Installation:

npx widdershins openapi.yaml -o api-docs.md

Das erzeugte Markdown ist Slate-kompatibel. Nützliche Optionen:

# YAML-Frontmatter weglassen
widdershins openapi.yaml --omitHeader -o api-docs.md

# Sprachen für Codebeispiele festlegen
widdershins openapi.yaml \
  --language_tabs 'shell:Shell' 'javascript:JavaScript' \
  -o api-docs.md

Geeignet für: Markdown, das Sie committen, diffen oder in ein bestehendes Dokumentationssystem übernehmen möchten.

Grenzen: Widdershins ist ein Konverter, kein Renderer. Für eine veröffentlichte Website benötigen Sie zusätzlich einen Markdown-Renderer oder Static-Site-Generator.

OpenAPI Generator: Dokumentation neben SDKs erzeugen

OpenAPI Generator ist vor allem für SDK-Generierung bekannt, enthält aber auch Dokumentationsgeneratoren. Verwenden Sie markdown für einen Markdown-Ordner oder html2 für statisches HTML.

npm install -g @openapitools/openapi-generator-cli

# Markdown-Dateien erzeugen
openapi-generator-cli generate \
  -g markdown \
  -i openapi.yaml \
  -o docs/

# HTML-Dokumentation erzeugen
openapi-generator-cli generate \
  -g html2 \
  -i openapi.yaml \
  -o docs-html/

Der npm-Wrapper lädt beim ersten Lauf ein JDK-basiertes Jar herunter. Danach bleibt der Workflow ein einzelner Generierungsbefehl.

Geeignet für: Teams, die bereits OpenAPI Generator für Client-SDKs einsetzen und Dokumentation mit demselben Tool erzeugen möchten.

Grenzen: Die Ausgabe basiert auf Vorlagen und ist eher schlicht. Der erste Aufruf ist schwergewichtiger als bei Widdershins oder Redocly CLI.

Redocly CLI: Eine eigenständige HTML-Datei erzeugen

Redocly CLI erzeugt mit build-docs eine einzelne HTML-Datei auf Basis von Redoc. Sie benötigen keinen Server und keinen separaten Website-Build.

npx @redocly/cli build-docs openapi.yaml

Standardmäßig entsteht die Datei redoc-static.html. Verwenden Sie --output, um einen eigenen Namen festzulegen:

npx @redocly/cli build-docs openapi.yaml --output api.html

Beispiel für CI:

npx @redocly/cli build-docs openapi.yaml --output public/api.html

Anschließend können Sie public/api.html auf einem statischen Host veröffentlichen oder als Build-Artefakt speichern.

Geeignet für: Eine polierte, teilbare API-Referenz als einzelne HTML-Datei.

Grenzen: Die Ausgabe ist eine einzelne Referenzseite, kein mehrseitiges Dokumentationsportal. Umfangreichere Theming- und Vorschaufunktionen liegen in kostenpflichtigen Redocly-Tarifen. Für Alternativen helfen diese Vergleiche zu Redocly-Alternativen und Scalar-Alternativen.

Slate: Handgeschriebene API-Dokumentation als statische Website

Slate ist kein OpenAPI-zu-Dokumentation-Konverter. Stattdessen ist es ein Static-Site-Generator für manuell gepflegte Markdown-Dokumentation mit einem klassischen dreispaltigen Layout: Navigation, Inhalt und Codebeispiele.

Slate basiert auf Middleman und benötigt Ruby. Nach dem Klonen des Repositories und der Installation der Abhängigkeiten erstellen Sie die Website mit:

bundle exec middleman build

Die statische Website liegt danach im Ordner build/ und kann auf jedem statischen Host bereitgestellt werden.

Ein praktikabler Workflow kombiniert Widdershins und Slate:

# 1. OpenAPI in Markdown umwandeln
widdershins openapi.yaml -o source/index.html.md

# 2. Slate-Website bauen
bundle exec middleman build

Geeignet für: Redaktionell kuratierte API-Dokumentation, bei der Sie Struktur, Erklärungen und Beispiele bewusst selbst schreiben oder bearbeiten möchten.

Grenzen: Slate benötigt eine Ruby-Toolchain und verarbeitet OpenAPI nicht direkt. Wenn Ihre Dokumentation vollständig automatisch aus der Spezifikation entstehen soll, ist ein direkter Konverter leichter.

Apidog CLI: Dokumentation aus einem API-Projekt exportieren

Die vorherigen Tools arbeiten primär mit einer einzelnen YAML- oder JSON-Datei. Wenn Ihre API bereits als Projekt gepflegt wird, kann die CLI von Apidog den Export nach Markdown oder HTML direkt übernehmen.

Installieren Sie die CLI und authentifizieren Sie sich per Token:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>

Exportieren Sie anschließend die Projektdokumentation:

# Markdown exportieren
apidog export \
  --project <projectId> \
  --format markdown \
  --output ./api-docs.md

# HTML exportieren
apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html

Die CLI kann außerdem Dokumentationsressourcen und veröffentlichte Dokumentationsseiten verwalten:

# Markdown-Dokumente eines Projekts auflisten
apidog doc list --project <projectId>

# Dokumentationsseiten eines Projekts auflisten
apidog docs-site list --project <projectId>

Die Ausgabe ist strukturiertes JSON und lässt sich daher gut in Shell-Skripte oder CI-Schritte integrieren.

Für den vollständigen Befehlsumfang lesen Sie den vollständigen Apidog-CLI-Leitfaden. Der Workflow für Markdown wird außerdem im Artikel zum API-Dokumentationsgenerator mit Markdown-Export detaillierter beschrieben.

Geeignet für: Teams, deren API bereits in einem verwalteten Projekt lebt und die Markdown oder HTML ohne manuelles Verketten von Konverter, Renderer und Hosting exportieren möchten.

Grenzen: Apidog ist nicht Open Source und arbeitet mit einem gehosteten Projekt. Die CLI ersetzt auch kein OpenAPI-Linting oder die Durchsetzung eines Styleguides; dafür eignen sich etwa Redocly und Spectral.

Wie Sie das passende Tool auswählen

Wählen Sie nach Eingabeformat und gewünschter Ausgabe:

Tool	Am besten für	Installation	Open Source?	Ausgabe
Widdershins	Spezifikation schnell in Markdown umwandeln	npm i -g widdershins	Ja (MIT)	Markdown
OpenAPI Generator	Dokumente neben SDKs generieren	npm i -g @openapitools/openapi-generator-cli	Ja (Apache 2.0)	Markdown oder HTML
Redocly CLI	Eine polierte HTML-Seite	npx @redocly/cli	Ja (MIT, Open Core)	Eigenständiges HTML
Slate	Manuell kuratierte Doku-Site	Ruby + Bundler	Ja (Apache 2.0)	Statische Website
Apidog CLI	Export aus einem Live-Projekt	npm i -g apidog-cli	Nein (kostenloser Tarif)	Markdown oder HTML

Die Kurzfassung:

• Verwenden Sie Widdershins, wenn Sie eine OpenAPI-Datei schnell in versionierbares Markdown umwandeln möchten.
• Verwenden Sie Redocly CLI, wenn Sie eine einzelne, veröffentlichungsfähige HTML-Datei benötigen.
• Verwenden Sie OpenAPI Generator, wenn SDKs und Dokumentation aus derselben Spezifikation entstehen sollen.
• Verwenden Sie Slate, wenn Ihre Dokumentation stark redaktionell gepflegt wird.
• Verwenden Sie Apidog CLI, wenn Ihre API bereits als Projekt verwaltet wird und Sie Export sowie Dokumentationsverwaltung per CLI benötigen.

Eine weitere Übersicht bietet die Zusammenfassung der kostenlosen API-Dokumentationstools.

Fazit

Wählen Sie das kleinste Tool, das Ihre gewünschte Ausgabe erzeugt.

Für die meisten Spezifikation-zu-Dokumentation-Workflows reichen Widdershins für Markdown oder redocly build-docs für statisches HTML. OpenAPI Generator ist sinnvoll, wenn Sie bereits SDKs generieren. Slate lohnt sich für manuell geschriebene Dokumentation mit eigenem Layout. Wenn Ihre API in einem Projekt statt nur in einer einzelnen Datei lebt, kann apidog-cli Markdown oder HTML ohne separate Build-Pipeline exportieren.

Wenn das auf Ihren Workflow zutrifft, laden Sie Apidog herunter und testen Sie apidog export in einem CI-Job, damit Ihre Dokumentation bei API-Änderungen neu erzeugt wird.