Sie haben eine OpenAPI-Datei und möchten daraus Dokumente erstellen. Sie möchten keinen Dienst einrichten, sich bei einem Portal anmelden oder einen Build-Schritt hinzufügen, der die Hälfte von npm mit sich zieht. Sie möchten einen einzigen Befehl, der die Spezifikation liest und Ihnen eine Markdown-Datei oder eine einzelne HTML-Seite liefert, die Sie überall hosten können.
Dafür ist diese Liste da. Jedes Tool hier ist klein: eine einzelne Binärdatei, ein npx-Einzeiler oder ein Paket, das Sie einmal installieren und vergessen. Sie starten schnell, benötigen wenig oder keine Konfiguration und erledigen die Dokumentationsarbeit, ohne eine vollständige Plattform mitzuschleppen. Einige geben Markdown aus, das Sie in eine bestehende Dokumentationsseite einfügen können. Andere geben eine eigenständige HTML-Datei aus. Alle laufen in CI und in einem Terminal, was der springende Punkt ist.
Wenn Sie das breitere Feld der Dokumentationsplattformen erkunden möchten, deckt die Zusammenfassung der Top 10 REST API-Dokumentationstools den GUI-lastigen Bereich ab. Dieser Artikel ist der terminalbasierte Ansatz mit geringem Ressourcenverbrauch. Als offizielle Referenz dafür, was ein Dokumentationsgenerator liest, ist die OpenAPI-Spezifikation die Quelle der Wahrheit, die jedes der unten genannten Tools parst.
Was ein CLI-Tool für die API-Dokumentation „leichtgewichtig“ macht
Leichtgewichtig bedeutet nicht, leistungsschwach zu sein. Es geht um Ressourcenverbrauch und Reibung. Vier Dinge entscheiden darüber.
Installationsgröße und Abhängigkeiten. Eine Binärdatei oder ein npm-Paket ist besser als ein Framework. Wenn das Generieren einer Dokumentationsseite die Installation einer Sprachlaufzeit plus eines Bundlers plus eines Plugin-Systems bedeutet, ist das nicht leichtgewichtig, egal wie die Ausgabe aussieht.
Start und Konfiguration. Die besten dieser Tools lesen Ihre Spezifikation und erzeugen eine Ausgabe ohne Konfiguration. Sie richten den Befehl auf openapi.yaml und erhalten eine Datei zurück. Alles, was eine Konfigurationsdatei benötigt, bevor es überhaupt läuft, verliert hier Punkte.
Einfacher Zweck der Ausgabe. Jedes der unten genannten Tools tut eine Sache: Spezifikation rein, Dokumente raus. Markdown oder HTML, nichts Weiteres angehängt. Das hält sie schnell und vorhersehbar in einer Pipeline.
Läuft überall. Keine GUI, keine Anmeldung für die offenen Tools, kein Server, der am Leben erhalten werden muss. Es funktioniert auf Ihrem Laptop und genauso in einem CI-Job. Für eine breitere Palette kostenloser Optionen enthält die Liste der kostenlosen API-Dokumentationstools die Plattformen; dies ist der CLI-Ausschnitt davon.
Nun zu den Tools, beginnend mit dem kleinsten.
Widdershins
Widdershins ist so klein wie es nur geht. Es ist ein einzelnes npm-Paket, das eine OpenAPI 3-, Swagger 2- oder AsyncAPI-Datei in Markdown konvertiert. Das ist die ganze Aufgabe. Es rendert keine Website und betreibt keinen Server; es liefert Ihnen eine .md-Datei und geht aus dem Weg.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Das von ihm erzeugte Markdown ist Slate-kompatibel, was wichtig ist, wenn Sie es später in eine statische Seite einspeisen möchten. Nützliche Flags: --omitHeader lässt den YAML-Frontmatter weg, und --language_tabs steuert, welche Code-Beispiel-Sprachen angezeigt werden.
Am besten geeignet für: Das Übertragen von Spezifikationsinhalten in Markdown, das Sie committen, diffen und in jedes Dokumentationssystem einfügen können. Ehrliche Grenzen: Markdown ist alles, was Sie bekommen. Es gibt keine Formatierung, kein interaktives "Ausprobieren"-Panel und keine gehostete Ausgabe. Widdershins ist ein Konverter, kein Renderer, daher kombinieren Sie es mit etwas, das Markdown in eine Site umwandelt.
OpenAPI Generator (Dokumentationsgeneratoren)
OpenAPI Generator ist am besten für Client-SDKs bekannt, liefert aber auch Dokumentationsgeneratoren, und diese sind praktisch, wenn eine Spezifikation alles ist, was Sie haben. Der markdown-Generator schreibt einen Ordner mit Markdown; der html2-Generator schreibt eine einzelne, eigenständige HTML-Seite. Sie können es über den npm-Wrapper steuern, ohne Java selbst installieren zu müssen.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Der npm-Wrapper lädt im Hintergrund immer noch ein JDK-gestütztes Jar herunter, daher ist er beim ersten Ausführen schwerer als Widdershins. Danach ist es ein Ein-Befehl-Generierungsprozess.
Am besten geeignet für: Die Wiederverwendung eines Tools, das Sie möglicherweise bereits für SDKs verwenden, um auch Dokumente zu erzeugen, mit einer Wahl zwischen Markdown und eigenständigem HTML. Ehrliche Grenzen: Die Ausgabe ist einfach und Vorlagen-basiert, und der erste Aufruf lädt ein Jar herunter, daher ist es nicht wirklich eine einzige Binärdatei. Wenn Sie nur Dokumente und nichts anderes benötigen, gibt es leichtere Optionen.
Redocly CLI (build-docs)
Wenn Sie eine gut aussehende, eigenständige HTML-Seite mit einem einzigen Befehl wünschen, ist Redocly CLI der kürzeste Weg. Der Befehl build-docs bündelt Ihre Spezifikation in eine einzige, in sich geschlossene HTML-Datei, die auf Redoc basiert. Kein Server, kein separater Hosting-Build; Sie erhalten eine Datei, die Sie öffnen, per E-Mail versenden oder auf jedem statischen Host ablegen können.
npx @redocly/cli build-docs openapi.yaml
Standardmäßig schreibt es redoc-static.html. Ändern Sie den Namen mit --output:
npx @redocly/cli build-docs openapi.yaml --output api.html
Da es über npx läuft, müssen Sie es nicht einmal global installieren, um es auszuprobieren. Am besten geeignet für: Eine polierte Einzel-Seiten-Referenz mit einem Befehl, mit einem sauberen Standardthema und ohne die Notwendigkeit, ein Hosting zu verwalten. Ehrliche Grenzen: Die Ausgabe ist eine HTML-Datei, es handelt sich also um eine Referenzseite und nicht um ein mehrseitiges Dokumentationsportal, und die umfangreicheren Theming- und Vorschau-Funktionen befinden sich in den kostenpflichtigen Tarifen von Redocly. Wenn Sie es mit ähnlichen Renderern vergleichen, legen die Vergleiche von Redocly-Alternativen und Scalar-Alternativen die Kompromisse dar.
Slate
Slate ist hier der Ausreißer: Es ist kein Spezifikations-zu-Dokumentations-Konverter, sondern ein Static-Site-Generator für handgeschriebene API-Dokumente. Sie schreiben Markdown, und Slate erstellt das klassische dreispaltige Dokumentationslayout (Navigation, Inhalt und Codebeispiele nebeneinander) in einer eigenständigen statischen Website. Es basiert auf Middleman und benötigt daher Ruby.
# nach dem Klonen des Slate-Repositorys und der Installation der Abhängigkeiten
bundle exec middleman build
Das schreibt eine vollständige statische Website in einen build/-Ordner, den Sie überall hosten können. Hier zahlt sich Widdershins aus: Generieren Sie Markdown aus Ihrer Spezifikation, lassen Sie es dann von Slate rendern, und Sie erhalten Spezifikations-gesteuerten Inhalt im Slate-Layout.
Am besten geeignet für: Von Hand kuratierte, erzählerische API-Dokumentation, bei der Sie die redaktionelle Kontrolle über Struktur und Text wünschen. Ehrliche Grenzen: Es ist die schwerste Option auf dieser Liste, da es eine Ruby-Toolchain benötigt, und es liest OpenAPI nicht von selbst; Sie füttern es mit Markdown. Wenn Ihre Dokumentation direkt aus einer Spezifikation generiert und selten manuell bearbeitet wird, ist ein Konverter allein leichter.
Apidog CLI (export + doc)
Die oben genannten Open-Source-Tools decken jeweils einen Bereich ab: konvertieren, rendern oder hosten. Wenn Ihre API bereits in einem Projekt und nicht in einer einzelnen YAML-Datei liegt, ist das Zusammenfügen der Reibungspunkt. Hier kommt die Binärdatei apidog-cli ins Spiel. Es ist der Befehlszeilen-Begleiter zu Apidog, und ein Export verwandelt ein Projekt in Markdown oder HTML ohne eine Build-Pipeline.
Installieren Sie es von npm und authentifizieren Sie sich mit einem Token:
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Exportieren Sie dann die Dokumentation des Projekts in einem Befehl nach Markdown oder HTML:
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
Die CLI verwaltet auch Dokumentationsressourcen direkt. apidog doc verarbeitet die Markdown-Dokumente des Projekts, und apidog docs-site verwaltet veröffentlichte Dokumentationsseiten, sodass Sie Dokumente von einem Skript oder CI-Job aus auflisten, erstellen und aktualisieren können:
apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
Die Ausgabe ist strukturiertes JSON, was es einfach macht, sie in andere Schritte zu pipen oder an einen Agenten weiterzureichen. Für den vollen Befehlsumfang führt der vollständige Apidog CLI-Leitfaden durch Authentifizierung, Projekte und jede Befehlsgruppe.
Hier ist die ehrliche Einordnung. Apidog ist kein Open Source und auch keine reine Binärdatei; es ist eine Freemium-Plattform, und die CLI kommuniziert mit einem gehosteten Projekt. Es lintert auch keine OpenAPI-Spezifikationen und erzwingt keinen Styleguide; das tun Redocly und Spectral. Was die CLI Ihnen bietet, ist ein integrierter Weg von einem gepflegten API-Projekt zu teilbarem Markdown oder HTML, anstatt einen Konverter, einen Renderer und einen Host manuell zu verketten. Wenn Sie speziell den Markdown-Exportweg wünschen, geht der Artikel API-Dokumentationsgenerator mit Markdown-Export tiefer auf diesen Workflow ein.
Wie man wählt
Passen Sie das Werkzeug an die Form Ihrer Eingabe und die benötigte Ausgabe an.
| Tool | Am besten für | Installation | Open Source? | Ausgabe |
|---|---|---|---|---|
| Widdershins | Spezifikation schnell zu Markdown | npm i -g widdershins |
Ja (MIT) | Markdown |
| OpenAPI Generator | Dokumente neben SDKs | 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 Dokus-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: Wenn Sie eine reine Spezifikation haben und Markdown zum Commit benötigen, verwenden Sie Widdershins. Wenn Sie eine einzige, teilbare HTML-Seite wünschen, ist redocly build-docs am schnellsten. Wenn Sie Dokumente von Hand schreiben und ein richtiges Layout wünschen, ist Slate die Wahl. Und wenn Ihre API bereits in einem Projekt und nicht in einer einzelnen Datei lebt und Sie Export plus Dokumentenmanagement in einer CLI wünschen, Apidog. Für einen kostenlosen Überblick über alle Optionen fasst die Zusammenfassung der kostenlosen API-Dokumentationstools alles zusammen.
Fazit
Leichtgewichtige Dokumentationstools lassen sich auf eine Regel reduzieren: Wählen Sie das kleinste Werkzeug, das die benötigte Ausgabe erzeugt. Widdershins und redocly build-docs decken die meisten Spezifikations-zu-Dokumentations-Fälle mit einem einzigen Befehl ab. Der OpenAPI Generator lohnt sich, wenn Sie bereits SDKs generieren. Slate rechtfertigt seinen höheren Ressourcenverbrauch nur, wenn Sie Dokumente von Hand schreiben. Und wenn Ihre API in einem echten Projekt und nicht in einer einzelnen Datei lebt, bietet der apidog-cli-Export Markdown oder HTML ohne eine Pipeline.
Wenn dieser letzte Fall auf Sie zutrifft, laden Sie Apidog herunter und probieren Sie apidog export für ein Projekt aus; es lässt sich sauber in einen CI-Job integrieren, sodass Ihre Dokumente bei jeder API-Änderung neu erstellt werden.