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

Wenn Sie ein Tool zur Generierung Ihrer API-Dokumentation auswählen, ist die Lizenz Teil der Entscheidung. Ein Open-Source-Generator bedeutet, dass Sie den Code lesen, die Ausgabe selbst hosten, ihn forken können, wenn er stagniert, und nie an eine Nutzerbeschränkung oder Paywall für eine Funktion stoßen, die Sie bereits ausgeliefert haben. Für einen Job, der in jedem CI-Build läuft, ist das genauso wichtig wie die Qualität der Ausgabe.

Diese Liste ist der Open-Source-Querschnitt von API-Dokumentations-Tools, die über die Kommandozeile ausgeführt werden. Jedes hier aufgeführte Tool ist quelloffen unter einer echten Lizenz, MIT oder Apache 2.0, auf GitHub gehostet und kostenlos ohne Registrierung nutzbar. Sie weisen es auf eine OpenAPI- oder Swagger-Datei und es liefert Ihnen Markdown, eine statische HTML-Seite oder eine vollständige Dokumentations-Website, die Sie selbst besitzen und hosten.

Ich werde die genaue Lizenz und die Möglichkeit des Selbsthostens für jedes Tool hervorheben, denn das ist der Grund, warum Sie eine Open-Source-Übersicht statt einer allgemeinen lesen. Wenn Sie das breitere Feld wünschen, deckt die Übersicht der Top 10 REST API-Dokumentationstools auch die GUI-Plattformen ab. Die OpenAPI-Spezifikation ist das Format, das jedes der folgenden Tools liest, daher ist eine gültige Spezifikation Ihr Ausgangspunkt.

Eine ehrliche Anmerkung vorab: Apidog erscheint gegen Ende und ist kein Open-Source-Eintrag; es ist eine kommerzielle Freemium-Plattform. Ich habe es nur als gekennzeichnete Randbemerkung für den Fall aufgenommen, dass die Open-Source-Tools eine Lücke lassen, und ich werde dies explizit klarstellen.

Was ein CLI-Dokumentationstool „Open Source“ macht

Open Source ist nicht nur „kostenlos herunterzuladen“. Für Dokumentationstools, die Sie in einen Build integrieren, entscheiden drei Dinge, ob ein Tool wirklich Ihnen gehört.

Eine echte Lizenz. MIT oder Apache 2.0 bedeutet, dass Sie das Tool kommerziell nutzen, modifizieren und weitergeben können, ohne um Erlaubnis fragen zu müssen. Beide sind OSI-anerkannt. Apache 2.0 fügt eine explizite Patenterteilung hinzu, die einige Rechtsteams bevorzugen. Jedes der folgenden Tools trägt eine der beiden Lizenzen.

Selbst-hostbare Ausgabe. Der Sinn offener Dokumentationen ist, dass nichts von den Servern eines Anbieters abhängt. Diese Tools schreiben statische Dateien: Markdown, das Sie committen, eine einzelne HTML-Seite oder einen Ordner mit HTML/CSS/JS. Sie hosten es auf GitHub Pages, S3 oder einem einfachen Nginx-Server, und es funktioniert weiter, unabhängig davon, ob das Projekt hinter dem Tool noch aktiv ist.

Wartung und Community. Quelloffenheit hilft nur, wenn der Code lebendig ist. Sterne, aktuelle Commits und offene Issues zeigen Ihnen, ob ein Fork machbar wäre, falls Sie jemals einen benötigen. Ein paar Tools hier sind archiviert, funktionieren aber noch; das werde ich erwähnen.

Für den Kostenlos-Aspekt bei sowohl Open-Source- als auch Freemium-Optionen ist die Liste der kostenlosen API-Dokumentationstools der Begleitartikel. Nun zu den Tools.

Redocly CLI

Redocly CLI ist der schnellste Weg, eine Spezifikation in eine ausgefeilte, eigenständige HTML-Referenz umzuwandeln. Es ist MIT-lizenziert und Open Core: Die CLI und die zugrunde liegende Redoc Rendering-Engine sind Open Source auf GitHub, während einige gehostete Portalfunktionen im kostenpflichtigen Produkt von Redocly enthalten sind. Der build-docs-Befehl gehört vollständig zum offenen Teil.

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

Das schreibt eine HTML-Datei, die auf Redoc basiert. Öffnen Sie sie lokal, legen Sie sie auf einem beliebigen statischen Host ab oder fügen Sie sie einer Veröffentlichung hinzu. Nichts sendet Daten nach Hause, und Sie können sie offline ausführen, sobald das Paket im Cache ist.

Am besten geeignet für: eine saubere einseitige API-Referenz mit einem Befehl, MIT-lizenziert und selbst gehostet. Ehrliche Einschränkungen: Die Ausgabe ist eine einzige Seite, also eine Referenz und kein mehrseitiges Portal, und die umfangreicheren Theme-Optionen sind in der kostenpflichtigen Version enthalten. Wenn Sie die Rendering-Engines gegeneinander abwägen, zeigt der Redocly-Alternativen-Vergleich auf, wo die Open-Source-Grenze verläuft.

Widdershins

Widdershins ist ein reiner Konverter unter der MIT-Lizenz. Es liest OpenAPI 3, Swagger 2 oder AsyncAPI und gibt Markdown aus; das ist die gesamte Aufgabe. Da die Ausgabe einfaches Markdown ist, besitzen Sie es vollständig: committen Sie es, differenzieren Sie es in einem Pull Request oder speisen Sie es in jede statische Website ein, die Sie bereits betreiben.

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

Das von ihm geschriebene Markdown ist Slate-kompatibel, was es hervorragend mit den Website-Generatoren dieser Liste kombiniert. Nützliche Flags: --omitHeader entfernt den Front-Matter-Bereich, und --language_tabs wählt die Sprachen für die Codebeispiele aus.

Am besten geeignet für: Spezifikationsinhalte in versionskontrollierbares Markdown zu überführen, ohne Vendor-Lock-in. Ehrliche Einschränkungen: Markdown ist alles, was Sie bekommen. Es gibt kein Styling und keine gerenderte Website, daher ist Widdershins eine Hälfte einer Pipeline; etwas anderes wandelt das Markdown in Seiten um.

OpenAPI Generator

OpenAPI Generator ist Apache 2.0-lizenziert und community-betrieben, 2018 von Swagger Codegen geforkt. Es ist am bekanntesten für Client-SDKs, bietet aber auch Dokumentationsgeneratoren: Der markdown-Generator schreibt einen Ordner mit Markdown-Dateien, und html2 schreibt eine einzige, eigenständige HTML-Seite.

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/

Die Apache 2.0-Lizenz und ihre Patenterteilung machen sie für vorsichtige Rechtsteams leicht genehmigbar, und das Projekt ist eines der am aktivsten gewarteten in diesem Bereich.

Am besten geeignet für: die Wiederverwendung eines Tools für SDKs und Dokumentation, unter einer permissiven Lizenz mit starker Community-Unterstützung. Ehrliche Einschränkungen: Der npm-Wrapper lädt beim ersten Ausführen immer noch eine Java-JAR-Datei herunter, es ist also kein einzelnes Binärprogramm, und die templatisierte Ausgabe ist schlicht. Wenn Sie nur Dokumentation benötigen, gibt es leichtere Konverter.

Swagger Codegen

Swagger Codegen ist der ursprüngliche, vorlagenbasierte Generator vom Swagger-Team, lizenziert unter Apache 2.0. Es existierte vor dem Fork des OpenAPI Generators und wird immer noch von SmartBear gewartet. Für Dokumentationen bietet es zwei Wege: html für eine statische einseitige Referenz und dynamic-html für eine kleine interaktive Website.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

Die beiden Projekte teilen DNA und viele Optionen, sodass Sie, wenn Ihr Team bereits auf die Swagger-Toolchain standardisiert ist, in dieser bleiben können.

Am besten geeignet für: Teams, die bereits im Swagger-Ökosystem investiert sind und Dokumentation vom selben Apache 2.0-Tool wünschen, das ihre Stubs generiert. Ehrliche Einschränkungen: Es ist wie OpenAPI Generator Java-basiert, und die Entwicklung verläuft langsamer als beim Community-Fork. Für die meisten neuen Setups ist OpenAPI Generator die aktivere Wahl; Swagger Codegen punktet bei der Kontinuität.

Docusaurus mit dem OpenAPI-Plugin

Wenn eine einzelne HTML-Seite nicht ausreicht und Sie eine echte, versionierte Dokumentations-Website wünschen, ist Docusaurus der Open-Source-Anker. Es ist MIT-lizenziert, von Meta entwickelt und einer der am häufigsten verwendeten statischen Website-Generatoren im Web. Für sich allein rendert es Markdown und MDX; das docusaurus-openapi-docs-Plugin, ebenfalls MIT-lizenziert und von Palo Alto Networks gepflegt, fügt die Generierung von Spezifikationen zu Dokumentationen hinzu.

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

Nachdem das Plugin mit Ihrem Spezifikationspfad konfiguriert wurde, konvertiert gen-api-docs die OpenAPI-Datei in MDX-Seiten, die innerhalb der Docusaurus-Website gerendert werden, komplett mit einem „Ausprobieren“-Panel und einer Seitenleistennavigation.

Am besten geeignet für: ein vollständiges, selbst gehostetes Dokumentationsportal mit Versionierung, Suche und handgeschriebenen Anleitungen neben der generierten Referenz. Ehrliche Einschränkungen: Dies ist das aufwendigste Setup hier. Sie richten eine React-Website und einen Build-Schritt ein, daher ist es übertrieben, wenn Sie nur eine Referenzseite benötigen. Dafür ist Redocly CLI der schnellere Weg.

Slate

Slate ist das klassische Drei-Spalten-Layout für API-Dokumentationen: Navigation links, Fließtext in der Mitte, Codebeispiele rechts, alles als statische Website gerendert. Es ist Apache 2.0-lizenziert und basierend auf Middleman, benötigt also eine Ruby-Toolchain. Im Gegensatz zu den oben genannten Konvertern liest Slate OpenAPI nicht direkt; Sie schreiben Markdown, und Slate rendert es.

# after cloning your Slate fork and running bundle install
bundle exec middleman build

Das schreibt eine komplette statische Website in einen build/-Ordner, den Sie überall hosten können. Hier zahlt sich Widdershins aus: Konvertieren Sie Ihre Spezifikation in Markdown und lassen Sie Slate es dann in diesem wiedererkennbaren Layout rendern.

Am besten geeignet für: handverlesene, erzählende Dokumentationen, bei denen Sie redaktionelle Kontrolle über Struktur und Prosa wünschen, auf einer vollständig selbst gehosteten statischen Website. Ehrliche Einschränkungen: Das ursprüngliche Repository ist archiviert (der Betreuer hat sich zurückgezogen), obwohl es noch gebaut wird und Forks aktiv sind, und die Ruby-Abhängigkeit ist aufwendiger als ein npx-Einzeiler. Wenn Ihre Dokumentation direkt aus einer Spezifikation generiert wird, ist ein Konverter leichter.

Apidog CLI (ehrlich gesagt, keine Open-Source-Option)

Die oben genannten Tools sind alle Open Source, und jedes deckt einen Bereich ab: Konvertieren, Rendern oder Hosten einer statischen Datei. Die Lücke, die sie hinterlassen, ist ein Live-Projekt. Wenn Ihre API keine einzelne YAML-Datei ist, sondern ein gepflegtes Projekt mit Endpunkten, Schemas und Beispielen, müssen Sie einen Konverter, einen Renderer und einen Host manuell verketten und alle drei synchron halten.

Das ist die Lücke, die das apidog-cli-Binärprogramm füllt. Um bezüglich der Lizenz direkt zu sein: Apidog ist nicht Open Source. Es ist eine kommerzielle Freemium-Plattform mit einer kostenlosen Stufe, und die CLI kommuniziert mit einem gehosteten Projekt statt mit einer lokalen Spezifikation. Ich nehme es hier nur auf, damit der Vergleich ehrlich ist, was die offenen Tools abdecken und was nicht, und nicht als Open-Source-Option.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html

Ein Export wandelt das Projekt in Markdown oder HTML um, ohne Build-Pipeline, und apidog doc sowie apidog docs-site verwalten Dokumentationsressourcen über ein Skript. Die Ausgabe ist strukturiertes JSON, sodass sie sauber in CI oder einen Agenten überführt werden kann. Die vollständige Anleitung zum Apidog CLI führt durch die Authentifizierung und jede Befehlsgruppe. Wenn der Markdown-Export-Workflow das ist, wonach Sie suchen, geht der Artikel „API-Dokumentationsgenerator mit Markdown-Export“ tiefer.

Wo die Grenze verläuft: Die offenen Tools geben Ihnen Code, den Sie besitzen, Dateien, die Sie selbst hosten, und keine Anbieterabhängigkeit. Apidog bietet Ihnen einen integrierten Weg von einem gepflegten Projekt zu gemeinsam nutzbaren Dokumentationen, allerdings auf Kosten eines gehosteten Freemium-Produkts. Wählen Sie danach, ob Ihre Quelle der Wahrheit eine statische Spezifikation oder ein Live-Projekt ist.

So wählen Sie aus

Passen Sie Lizenz und Ausgabe an das an, was Ihr Team besitzen muss.

Kurz gesagt: Für eine reine Spezifikation und eine gemeinsam nutzbare HTML-Referenz verwenden Sie Redocly CLI. Für Markdown, das Sie versionskontrollieren möchten, Widdershins. Wenn Sie bereits SDKs generieren, erstellt OpenAPI Generator auch Dokumentationen, und Swagger Codegen deckt Sie ab, wenn Sie auf Swagger standardisiert sind. Wenn Sie ein echtes Portal mit Versionierung und Anleitungen wünschen, ist Docusaurus plus das OpenAPI-Plugin der Open-Source-Anker, und Slate ist die Wahl für handgeschriebene, redaktionell kontrollierte Dokumentationen. Jedes dieser Tools ist quelloffen und selbst hostbar, sodass nichts, was Sie veröffentlichen, davon abhängt, dass ein Anbieter im Geschäft bleibt. Für einen breiteren Überblick über kostenlose Optionen fasst die Übersicht der kostenlosen API-Dokumentationstools sowohl Open-Source- als auch Freemium-Optionen zusammen.

Zusammenfassung

Die Wahl eines Open-Source-Dokumentations-CLIs hängt von der Lizenz, der Ausgabe und dem Speicherort Ihrer Dokumentation ab. MIT und Apache 2.0 erlauben Ihnen beide die Nutzung, Änderung und das Selbsthosten ohne Lizenzkosten pro Benutzer, also wählen Sie das kleinste Tool, das die benötigte Ausgabe liefert: Redocly CLI für eine Seite, Widdershins für Markdown, OpenAPI Generator oder Swagger Codegen für Dokumentationen neben Ihren SDKs, Docusaurus für ein Portal, Slate für handverlesene Seiten.

Wenn Ihre API in einem gepflegten Projekt und nicht in einer einzelnen Datei liegt und Sie lieber Dokumentationen exportieren als drei Tools zu verketten, laden Sie Apidog herunter und versuchen Sie apidog export für ein Projekt. Es lässt sich in einen CI-Job integrieren, sodass Ihre Dokumentation jedes Mal neu erstellt wird, wenn sich die API ändert. Seien Sie sich jedoch bewusst, dass es sich um eine Freemium-Plattform und nicht um ein Open-Source-Binärprogramm handelt.