DEV Community

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

Posted on • Originally published at apidog.com

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

Wenn Sie ein Tool zur Generierung von API-Dokumentation auswählen, ist die Lizenz ein technisches Auswahlkriterium. Ein Open-Source-Generator lässt sich prüfen, selbst hosten und bei Bedarf forken. Außerdem vermeiden Sie Nutzerlimits oder Paywalls in einem CI-Schritt, der bei jedem Build laufen soll.

Apidog noch heute ausprobieren

Diese Übersicht konzentriert sich auf quelloffene CLI-Tools für API-Dokumentation. Jedes Tool liest eine OpenAPI- oder Swagger-Datei und erzeugt Markdown, statisches HTML oder eine komplette selbst hostbare Dokumentations-Website. Voraussetzung ist eine gültige OpenAPI-Spezifikation.

Ich hebe Lizenz und Self-Hosting explizit hervor: Das ist der entscheidende Unterschied zu einer allgemeinen Tool-Liste. Für GUI-Plattformen und weitere Optionen siehe die Übersicht der Top 10 REST-API-Dokumentationstools.

Hinweis: Apidog erscheint weiter unten als klar gekennzeichnete Freemium-Option. Es ist nicht Open Source und gehört nicht zur eigentlichen Open-Source-Auswahl.

Was ein CLI-Dokumentationstool wirklich Open Source macht

„Kostenlos herunterladbar“ reicht für einen Build-Schritt nicht aus. Prüfen Sie vor der Integration vor allem diese drei Punkte:

  1. Lizenz

    MIT und Apache 2.0 erlauben kommerzielle Nutzung, Änderungen und Weitergabe. Apache 2.0 enthält zusätzlich eine explizite Patenterteilung.

  2. Selbst hostbare Ausgabe

    Das Tool sollte Dateien erzeugen, die Sie selbst ausliefern können: Markdown, statisches HTML oder einen HTML/CSS/JS-Ordner. Damit können Sie die Dokumentation beispielsweise auf GitHub Pages, S3 oder Nginx hosten.

  3. Wartung und Community

    Prüfen Sie Commits, Issues und Forks. Archivierte Projekte können weiterhin funktionieren, verursachen aber mehr Betriebsrisiko.

Eine ergänzende Übersicht für kostenlose Open-Source- und Freemium-Optionen finden Sie bei den kostenlosen API-Dokumentationstools.

1. Redocly CLI

Redocly CLI erzeugt aus einer OpenAPI-Spezifikation schnell eine eigenständige HTML-Referenz. Die CLI und die Redoc-Rendering-Engine sind MIT-lizenziert und Open Source. Einige gehostete Portalfunktionen gehören zum kostenpflichtigen Redocly-Produkt, der Befehl build-docs jedoch zum offenen Teil.

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

Danach können Sie die erzeugte Datei lokal öffnen oder direkt auf einem statischen Host veröffentlichen:

# Beispiel: Ausgabe prüfen
open api-docs.html
Enter fullscreen mode Exit fullscreen mode

Redocly CLI

Geeignet für: Eine sauber gerenderte, selbst hostbare API-Referenz als einzelne HTML-Datei.

Einschränkungen: Die Ausgabe ist eine einzelne Referenzseite, kein mehrseitiges Portal. Umfangreichere Theme-Optionen gehören zu kostenpflichtigen Redocly-Angeboten. Für einen Vergleich ähnlicher Renderer siehe Redocly-Alternativen.

2. Widdershins

Widdershins ist ein MIT-lizenzierter Konverter für OpenAPI 3, Swagger 2 und AsyncAPI. Das Tool erzeugt Markdown und eignet sich deshalb gut für dokumentationsgetriebene Workflows mit Git, Pull Requests und statischen Site-Generatoren.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Praktische Optionen:

# Header bzw. Front Matter 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
Enter fullscreen mode Exit fullscreen mode

Widdershins

Geeignet für: OpenAPI-Inhalte als versionierbares Markdown in Ihr Repository zu übernehmen.

Einschränkungen: Widdershins rendert keine Website und liefert kein Styling. Es ist typischerweise der erste Schritt einer Pipeline, zum Beispiel vor Slate oder einem anderen Site-Generator.

3. OpenAPI Generator

OpenAPI Generator ist Apache-2.0-lizenziert und wird von der Community gepflegt. Das Projekt wurde 2018 von Swagger Codegen geforkt. Neben Client-SDKs kann es Dokumentation als Markdown oder HTML erzeugen.

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

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

# Eigenständige HTML-Ausgabe erzeugen
openapi-generator-cli generate \
  -g html2 \
  -i openapi.yaml \
  -o docs-html/
Enter fullscreen mode Exit fullscreen mode

Für CI können Sie die Generierung als Build-Schritt ausführen und die Ausgabe anschließend veröffentlichen:

openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
git diff --exit-code docs/
Enter fullscreen mode Exit fullscreen mode

OpenAPI Generator

Geeignet für: Teams, die SDKs und Dokumentation mit einem Apache-2.0-lizenzierten Tool erzeugen möchten.

Einschränkungen: Der npm-Wrapper lädt beim ersten Ausführen eine Java-JAR-Datei. Die Standard-Templates sind funktional, aber eher schlicht. Wenn Sie nur Markdown oder eine HTML-Referenz benötigen, ist ein spezialisierter Konverter oft leichter.

4. Swagger Codegen

Swagger Codegen ist der ursprüngliche vorlagenbasierte Generator aus dem Swagger-Ökosystem und steht unter Apache 2.0. Für Dokumentation stehen unter anderem html für eine statische Referenz und dynamic-html für eine kleine interaktive Website zur Verfügung.

npm install -g swagger-codegen-cli

swagger-codegen-cli generate \
  -i openapi.yaml \
  -l html \
  -o docs/
Enter fullscreen mode Exit fullscreen mode

Wenn Ihr Team bereits Swagger Codegen für Stubs oder Clients verwendet, bleibt die Toolchain damit konsistent.

Swagger Codegen

Geeignet für: Teams, die bereits auf Swagger Codegen standardisiert sind.

Einschränkungen: Wie OpenAPI Generator basiert es auf Java. Die Entwicklung verläuft langsamer als beim Community-Fork OpenAPI Generator. Für neue Setups ist OpenAPI Generator meist die aktivere Wahl; Swagger Codegen ist vor allem für bestehende Toolchains relevant.

5. Docusaurus mit OpenAPI-Plugin

Wenn eine einzelne Referenzseite nicht genügt, ist Docusaurus eine Open-Source-Basis für ein vollständiges Dokumentationsportal. Docusaurus ist MIT-lizenziert und rendert Markdown sowie MDX. Das ebenfalls MIT-lizenzierte Plugin docusaurus-openapi-docs erzeugt daraus API-Seiten aus Ihrer Spezifikation.

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all
Enter fullscreen mode Exit fullscreen mode

Nach der Plugin-Konfiguration zeigt gen-api-docs Ihre OpenAPI-Datei als MDX-Seiten in der Docusaurus-Website an. Dadurch können Sie generierte Referenzen mit handgeschriebenen Guides, Seitenleisten und Versionierung kombinieren.

npm run build
Enter fullscreen mode Exit fullscreen mode

Der Build erzeugt eine statische Website, die Sie selbst hosten können.

Docusaurus mit OpenAPI-Plugin

Geeignet für: Ein selbst gehostetes API-Portal mit Versionierung, Suche und zusätzlichen Anleitungen.

Einschränkungen: Das Setup ist umfangreicher als ein einzelner CLI-Aufruf. Sie betreiben eine React-basierte Website und einen zusätzlichen Build-Schritt. Für eine einzelne Referenzseite ist Redocly CLI meist der schnellere Weg.

6. Slate

Slate ist ein klassisches Layout für API-Dokumentation: Navigation links, Dokumentation in der Mitte und Codebeispiele rechts. Das Projekt ist Apache-2.0-lizenziert und basiert auf Middleman sowie Ruby.

Slate liest keine OpenAPI-Datei direkt. Stattdessen schreiben oder generieren Sie Markdown und lassen Slate daraus eine statische Website bauen. In Kombination mit Widdershins ergibt sich eine einfache Pipeline:

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

# 2. Statische Slate-Website erzeugen
bundle install
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Die fertige Website liegt anschließend im Verzeichnis build/ und kann auf jedem statischen Host veröffentlicht werden.

Geeignet für: Redaktionell gepflegte Dokumentation mit vollständiger Kontrolle über Struktur, Texte und Beispiele.

Einschränkungen: Das ursprüngliche Repository ist archiviert, funktioniert aber weiterhin; aktive Forks existieren. Die Ruby-Toolchain ist aufwendiger als ein npx-Befehl. Für vollständig spezifikationsgetriebene Dokumentation ist ein direkter Generator meist einfacher.

7. Apidog CLI: keine Open-Source-Option

Die bisherigen Tools decken Konvertierung, Rendering und Hosting statischer Dateien ab. Wenn Ihre API jedoch als gepflegtes Projekt mit Endpunkten, Schemas und Beispielen vorliegt, müssen Sie bei Open-Source-Tools oft mehrere Komponenten selbst verbinden und synchron halten.

Apidog CLI

Das apidog-cli-Binärprogramm adressiert diesen Workflow. Wichtig zur Einordnung: Apidog ist nicht Open Source. Es ist eine kommerzielle Freemium-Plattform mit kostenloser Stufe. Die CLI arbeitet mit einem gehosteten Projekt statt ausschließlich mit einer lokalen Spezifikation.

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

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

# Projekt als HTML exportieren
apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

Die CLI kann außerdem Dokumentationsressourcen skriptgesteuert verwalten. Für Authentifizierung und Befehlsgruppen siehe die vollständige Anleitung zum Apidog CLI. Für einen auf Markdown fokussierten Workflow lesen Sie API-Dokumentationsgenerator mit Markdown-Export.

Geeignet für: Export aus einem gepflegten, gehosteten API-Projekt.

Einschränkung: Die Plattform ist Freemium und nicht quelloffen. Sie vermeiden zwar eine eigene Pipeline aus Konverter, Renderer und Host, akzeptieren dafür aber eine Anbieterabhängigkeit.

So wählen Sie das passende Tool

Tool Am besten geeignet für Installation Open Source? Ausgabe
Redocly CLI Eine ausgefeilte HTML-Referenz npx @redocly/cli Ja, MIT / Open Core Eigenständiges HTML
Widdershins Spezifikation als Markdown im Repository npm i -g widdershins Ja, MIT Markdown
OpenAPI Generator Dokumentation und SDKs mit einem Tool npm i -g @openapitools/openapi-generator-cli Ja, Apache 2.0 Markdown oder HTML
Swagger Codegen Bestehende Swagger-Codegen-Toolchain npm i -g swagger-codegen-cli Ja, Apache 2.0 HTML
Docusaurus + OpenAPI-Plugin Vollständiges selbst gehostetes Portal npx create-docusaurus Ja, MIT Statische Website
Slate Manuell kuratierte Drei-Spalten-Dokumentation Ruby + Bundler Ja, Apache 2.0 Statische Website
Apidog CLI Export aus einem Live-Projekt npm i -g apidog-cli Nein, Freemium Markdown oder HTML

Als praktische Entscheidungshilfe:

  • Sie brauchen eine HTML-Referenz aus einer YAML-Datei: Redocly CLI.
  • Sie möchten Markdown versionieren und reviewen: Widdershins.
  • Sie generieren bereits SDKs: OpenAPI Generator oder Swagger Codegen.
  • Sie benötigen ein vollständiges Portal: Docusaurus mit OpenAPI-Plugin.
  • Sie möchten Inhalte redaktionell kuratieren: Slate.
  • Ihre Quelle der Wahrheit ist ein gehostetes API-Projekt: Apidog CLI, mit der Einschränkung, dass es nicht Open Source ist.

Für weitere kostenlose Alternativen siehe die Übersicht der kostenlosen API-Dokumentationstools.

Zusammenfassung

Die Wahl eines Open-Source-Dokumentations-CLIs hängt von drei Fragen ab:

  1. Welche Lizenz akzeptiert Ihr Team?
  2. Benötigen Sie Markdown, HTML oder ein vollständiges Portal?
  3. Liegt Ihre API als lokale Spezifikation oder als gepflegtes Live-Projekt vor?

Wählen Sie das kleinste Tool, das Ihre benötigte Ausgabe erzeugt:

  • Redocly CLI für eine einzelne HTML-Seite
  • Widdershins für Markdown
  • OpenAPI Generator oder Swagger Codegen für Dokumentation neben SDKs
  • Docusaurus für ein Portal
  • Slate für kuratierte statische Seiten

Wenn Ihre API in einem gepflegten Projekt statt in einer einzelnen Datei liegt und Sie lieber exportieren als mehrere Tools zu verketten, können Sie Apidog herunterladen und apidog export in Ihren CI-Workflow integrieren. Beachten Sie dabei: Apidog ist eine Freemium-Plattform, kein Open-Source-Binärprogramm.

Top comments (0)