API-Dokumentationen veralten in dem Moment, in dem jemand eine Spezifikation bearbeitet und vergisst, die Referenz neu zu generieren. Die Lösung besteht darin, die Dokumentation nicht mehr als manuellen Schritt zu behandeln. Wenn Sie Dokumente mit einem einzigen Befehl erstellen können, können Sie diesen Befehl in CI einbinden und bei jeder Zusammenführung ausführen lassen.
Die Ausführung über das Terminal hat weitere Vorteile. Befehle sind skriptfähig, sie hinterlassen einen Diff, den Sie überprüfen können, und ein KI-Agent oder ein CI-Runner kann sie auslösen, ohne dass jemand einen Browser öffnen muss. Kein GUI-Klicken, kein "Haben Sie daran gedacht, auf Exportieren zu klicken."
Dieser Leitfaden beschreibt zunächst den allgemeinen offenen Weg: die Umwandlung einer OpenAPI-Datei in eine eigenständige HTML-Referenz oder eine Markdown-Datei mit einem einzigen Befehl. Dann geht es tiefer in den Apidog CLI-Weg, der Ihre Dokumente direkt aus einem Live-Projekt zieht, sodass die Quelle der Wahrheit und die Ausgabe synchron bleiben. Wenn Sie mehr Hintergrundwissen über die Landschaft wünschen, sehen Sie sich unsere Zusammenfassung der Top 10 Tools für die REST-API-Dokumentation und der kostenlosen API-Dokumentationstools an, die es wert sind, bekannt zu sein.
Sie benötigen nur eines, um mitzumachen: eine OpenAPI 3.x-Datei. Die meisten dieser Befehle akzeptieren openapi.yaml oder openapi.json austauschbar.
HTML-Referenz mit Redocly CLI erstellen
Redocly CLI ist der schnellste Weg, eine OpenAPI-Beschreibung in eine polierte, eigenständige HTML-Seite umzuwandeln. Es rendert Ihre Spezifikation mit Redoc und schreibt alles (Stile, Skript und Inhalt) in eine einzige Datei, die Sie überall hosten oder einem Teamkollegen per E-Mail senden können.
Installieren Sie es global oder überspringen Sie die Installation und führen Sie es mit npx aus:
npm install @redocly/cli -g
Dann verweisen Sie es auf Ihre Spezifikation:
redocly build-docs openapi.yaml
Standardmäßig schreibt dies redoc-static.html in das aktuelle Verzeichnis. Öffnen Sie diese Datei in einem Browser und Sie haben eine vollständige dreiteilige API-Referenz. Um den Dateinamen oder Pfad zu steuern, verwenden Sie --output:
redocly build-docs openapi.yaml --output docs/index.html
Das ist der gesamte Workflow. Eine Eingabedatei, ein Befehl, ein HTML-Artefakt. Es funktioniert mit Swagger 2.0- und OpenAPI 3.0/3.1-Beschreibungen, sodass die meisten vorhandenen Spezifikationen ohne Änderungen gerendert werden. Der Kompromiss ist der Umfang: build-docs gibt Ihnen eine Referenzseite und nichts anderes. Langform-Anleitungen, Tutorials und Einstiegsseiten befinden sich außerhalb davon.
Markdown mit Widdershins generieren
Manchmal möchten Sie kein HTML. Sie möchten Markdown, das Sie in eine Dokumentationsseite, einen Static-Site-Generator oder den docs/-Ordner eines Repositories einfügen können. Widdershins konvertiert eine OpenAPI-, Swagger- oder AsyncAPI-Definition in Slate-kompatibles Markdown.
Installieren Sie es von npm:
npm install -g widdershins
Konvertieren Sie dann Ihre Spezifikation und senden Sie die Ausgabe mit -o an eine Datei:
widdershins openapi.yaml -o api.md
Lassen Sie -o weg und Widdershins gibt in stdout aus, was praktisch ist, wenn Sie es irgendwohin leiten möchten. Sie können auch Sprach-Tabs für Codebeispiele umschalten:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins ist eine gute Wahl, wenn Ihre Dokumentationspipeline Markdown-basiert ist. Wenn Sie einen breiteren Markdown-Export-Workflow aufbauen, behandelt unser Leitfaden zur Verwendung eines API-Dokumentationsgenerators mit Markdown-Export die begleitenden Tools. Der Haken bei Redocly und Widdershins ist derselbe: Sie lesen eine statische Datei. Wenn Ihre API-Definition in einem Design-Tool lebt und von der Datei auf der Festplatte abweicht, dokumentieren Sie die Spezifikation von gestern.
Dokumentieren Sie aus einem Live-Projekt mit der Apidog CLI
Hier zahlt sich der integrierte Weg aus. Apidog ist zwar nicht Open Source, aber seine kostenlose Stufe plus apidog-cli bietet Ihnen eine Alternative zum Zusammensetzen separater Tools: Ihre Endpunkte, Schemas und schriftlichen Dokumente leben alle in einem Projekt, und die CLI exportiert bei Bedarf aus diesem Projekt. Nichts driftet ab, da der Export dieselbe Quelle liest, die Ihr Team bearbeitet.
Installieren Sie die CLI von npm:
npm install -g apidog-cli
Wenn Sie sich zum ersten Mal einrichten, behandelt unser Apidog CLI-Installationsleitfaden Node-Versionen und PATH-Einrichtung. Authentifizieren Sie sich dann einmal mit einem persönlichen Zugriffstoken:
apidog login --with-token <TOKEN>
Das Token wird gespeichert, sodass Sie es nicht bei jedem Aufruf übergeben müssen. Von hier aus läuft alles mit einer Projekt-ID. Fügen Sie --help zu jedem Befehl hinzu, um seine genauen Flags zu sehen, bevor Sie ihn ausführen.
Eine Spezifikation in das Projekt importieren
Wenn Ihre API bereits in einer OpenAPI-Datei existiert, importieren Sie sie in ein Projekt, damit die CLI etwas zum Exportieren hat:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import akzeptiert OpenAPI 3.x-, Swagger 2.0-, Postman- und Apidog-Formate, sodass Sie eine Postman-Sammlung oder einen vorhandenen Apidog-Export auf dieselbe Weise importieren können. Sobald die Spezifikation importiert ist, wird sie zur Live-Quelle, aus der alles andere liest.
Menschenlesbare Dokumente exportieren
Dies ist der Kernbefehl. apidog export schreibt OpenAPI, HTML, Markdown oder Postman. Führen Sie also zuerst --help aus, um das genaue Format und die Ausgabeflags Ihrer Version zu sehen, und exportieren Sie dann die Projektdokumentation nach Markdown:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Öffnen Sie api-docs.md und Sie haben eine vollständige Referenz, die aus dem aktuellen Zustand des Projekts generiert wurde. Möchten Sie stattdessen HTML? Ändern Sie ein Flag:
apidog export --project <projectId> --format html --output ./api-docs.html
Sie können auch zurück nach OpenAPI exportieren, wenn Sie eine portable Spezifikation für nachgeschaltete Prozesse benötigen:
apidog export --project <projectId> --format openapi --output ./openapi.json
Wenn Ihr Projekt mehrere Dienste enthält und Sie nur einen Teil davon dokumentieren möchten, unterstützt der Export die Einschränkung des Umfangs. Überprüfen Sie apidog export --help für die Umfangs- und ID-Flags in Ihrer Version, da ein einzelnes Projekt auf diese Weise eine Doc-Datei pro Dienst ausliefern kann.
Die schriftlichen Anleitungen verwalten, nicht nur die Referenz
Eine aus Ihrem Schema generierte Referenz ist nur die halbe Miete. Die andere Hälfte ist der Text: Erste Schritte-Anleitungen, Authentifizierungs-Walkthroughs, Migrationshinweise. In Apidog leben diese im Dokumentenbaum des Projekts als Markdown-Dokumente, und die CLI verwaltet sie mit der Befehlsgruppe doc.
Beginnen Sie mit dem Lesen der Hilfe der Gruppe, damit Sie mit den exakten Flags Ihrer Version arbeiten:
apidog doc --help
apidog doc list --project <projectId>
Von dort ist der Workflow derselbe wie alles andere in der CLI: Führen Sie den Befehl für Ihr Projekt aus, lesen Sie das JSON-Ergebnis und folgen Sie den agentHints.nextSteps, die es zurückgibt. Wenn ein Befehl eine JSON-Nutzlast benötigt, kann die CLI das erwartete Schema ausgeben und Ihre Datei vor dem Senden dagegen validieren, sodass Sie ein fehlendes Feld auf Ihrer Maschine und nicht in einem fehlgeschlagenen Aufruf abfangen. Überprüfen Sie apidog cli-schema --help für den genauen Unterbefehl zur Validierung.
Eine Dokumentationsseite veröffentlichen
Wenn Referenz und Anleitungen fertig sind, können Sie die veröffentlichte Dokumentation auch über das Terminal verwalten. Zwei Befehle decken dies ab, und das vorherige Lesen ihrer Hilfe erspart ein geratenes Flag:
apidog docs-site --help
apidog shared-doc --help
Ein Namenshinweis, der Menschen in die Irre führt: Ein doc ist ein Markdown-Dokument innerhalb des API-Baums des Projekts, docs-site verwaltet die gehostete, öffentliche Dokumentationsseite und shared-doc verwaltet teilbare Dokumentationslinks. Greifen Sie zu docs-site, wenn Sie eine öffentliche Website vom Terminal aus definieren möchten, anstatt sie in einer Benutzeroberfläche zusammenzuklicken, und zu shared-doc, wenn Sie nur einen Link an einen Partner übergeben möchten. Der Vorteil ist, dass die Veröffentlichung zu einem skriptgesteuerten Schritt wird: Wenn sich Ihre Spezifikation ändert, importieren oder bearbeiten Sie das Projekt erneut, führen dann den Veröffentlichungsbefehl erneut aus, und die gehosteten Dokumente spiegeln das Update wider.
In CI einbinden
Der Grund, warum all dies über die CLI ausgeführt werden sollte, ist die Wiederholbarkeit. Sobald die Befehle lokal funktionieren, funktionieren sie auch in einer Pipeline. Ein minimaler GitHub Actions-Schritt, der Ihre Markdown-Referenz bei jedem Push neu generiert und committet, sieht wie folgt aus:
- 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
Ersetzen Sie redocly build-docs oder widdershins und die Form ist identisch. Dokumente hören auf, eine lästige Pflicht zu sein, an die sich jemand erinnern muss, und werden zu einem Build-Artefakt, das sich selbst regeneriert. Eine vollständige Befehlsreferenz finden Sie im vollständigen Leitfaden zur Apidog CLI.
Häufige Fallstricke
Falsche oder fehlende Projekt-ID. Jeder Apidog export-, doc- und docs-site-Aufruf benötigt --project <projectId>. Die ID befindet sich in den Projekteinstellungen, nicht im menschenlesbaren Projektnamen. Wenn ein Befehl mit einer Beschwerde über das Projekt fehlschlägt, ist dies fast immer die Ursache.
Token nicht in CI gesetzt. apidog login speichert das Token auf der Maschine, die es ausführt. In einem frischen CI-Runner gibt es kein gespeichertes Token, daher müssen Sie login --with-token im selben Job vor jedem Export ausführen. Speichern Sie das Token als Geheimnis, niemals in der Workflow-Datei.
Veraltete Dateiexporte. Redocly und Widdershins lesen jede Datei, die Sie ihnen geben. Wenn Ihre openapi.yaml veraltet ist, sind es auch Ihre Dokumente. Dies ist genau die Abweichung, die der Apidog-Weg vermeidet, indem er aus dem Live-Projekt anstatt aus einer Datei auf der Festplatte exportiert.
Flags erraten, anstatt --help zu lesen. Die genauen Flags für export, doc, docs-site und shared-doc können je nach CLI-Version variieren. Führen Sie apidog <command> --help aus und arbeiten Sie mit dem, was es ausgibt, anstatt mit einem Flag, an das Sie sich nur halb erinnern. Das dauert zwei Sekunden und erspart einen fehlgeschlagenen Build.
Zusammenfassung
Die Dokumentation einer API über das Terminal läuft auf die Wahl der richtigen Ausgabe hinaus. Greifen Sie zum Redocly CLI, wenn Sie eine eigenständige HTML-Referenz wünschen, zu Widdershins, wenn Sie Markdown für eine Dokumentationsseite möchten, und zur Apidog CLI, wenn Sie eine Referenz plus schriftliche Anleitungen plus eine veröffentlichte Website, alles aus einer Live-Quelle exportiert, wünschen. Die letzte Option ist diejenige, die Ihre Dokumente aktuell hält, denn der Export und das, was Ihr Team bearbeitet, sind dasselbe Projekt.
Jeder Befehl hier ist skriptfähig, was bedeutet, dass jeder von ihnen in CI gehört. Einmal eingerichtet, regeneriert sich Ihre Dokumentation bei jeder Änderung selbst. Laden Sie Apidog herunter, um die CLI zu erhalten und den Export-Workflow für Ihr eigenes Projekt auszuprobieren, oder erfahren Sie mehr darüber, wie Apidog in einen API-First-Workflow passt.