OpenAPI Specs automatisch in saubere Markdown-Doku konvertieren

Wählen Sie nach Ziel: einfache Repository-Referenz, statische Docs, internes Format oder vollständig integrierter API-Workflow.

Methode 1: OpenAPI mit einem Einzeiler in Markdown konvertieren

Für eine schnelle Repository-Referenz reicht oft ein dedizierter Konverter.

Node.js: openapi-to-md

openapi-to-md nimmt OpenAPI v2 oder v3 in YAML oder JSON und erzeugt eine Markdown-Datei.

npx openapi-to-md openapi.yaml api-reference.md 

Typischer Einsatz im Projekt:

mkdir -p docs npx openapi-to-md openapi.yaml docs/api-reference.md 

Danach können Sie die Datei direkt ins Repository committen:

git add docs/api-reference.md git commit -m "docs: generate API reference" 

Python: openapi-markdown

Für Python-basierte Toolchains können Sie openapi-markdown verwenden:

pip install openapi-markdown openapi2markdown openapi.yaml api-reference.md 

Beide Varianten lesen Pfade, Operationen, Parameter und Schemas aus der Spezifikation und erzeugen daraus Markdown mit Überschriften und Tabellen.

Wann diese Methode passt:

• Sie brauchen schnell eine lesbare Datei.
• Das Standardlayout reicht aus.
• Sie wollen die Ausgabe regelmäßig neu generieren.
• Sie benötigen keine stark angepassten Templates.

Grenze: Sie bekommen das Layout des Tools. Wenn Ihr Team bestimmte Abschnitte, Codebeispiele oder Dateiaufteilungen benötigt, ist Widdershins oder ein eigenes Skript besser.

Methode 2: Widdershins für anpassbare Dokumentation mit Codebeispielen

Widdershins ist ein etabliertes Node-Tool, das OpenAPI oder Swagger in Slate-kompatibles Markdown umwandelt. Es eignet sich besonders, wenn Sie Code-Tabs und anpassbare Templates brauchen.

Installation:

npm install -g widdershins 

Basis-Konvertierung:

widdershins openapi.yaml -o api-reference.md 

Mit Sprachbeispielen:

widdershins \ --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \ openapi.yaml \ -o api-reference.md 

Ohne automatisch erzeugten Header, wenn Ihr Docs-Framework eigenen Front Matter verwendet:

widdershins \ --language_tabs 'shell:cURL' 'python:Python' 'javascript:JavaScript' \ --omitHeader \ openapi.yaml \ -o api-reference.md 

Wann Widdershins passt:

• Sie bauen eine statische Dokumentationsseite.
• Sie möchten Codebeispiele für mehrere Sprachen.
• Sie brauchen mehr Kontrolle als bei einfachen Konvertern.
• Sie akzeptieren einen zusätzlichen Build-Schritt.

Der Trade-off: Sie besitzen jetzt ein Template und müssen es pflegen. Für ein Docs-Repository ist das meist sinnvoll, für eine einfache README oft zu viel.

Methode 3: Eigenes Skript für ein exaktes Layout

Wenn kein Konverter Ihr gewünschtes Format erzeugt, parsen Sie die OpenAPI-Datei selbst. Die Spezifikation ist strukturierte YAML- oder JSON-Daten.

Beispiel: Ein minimales Node.js-Skript, das jede Operation in Markdown schreibt.

import { readFileSync, writeFileSync } from "node:fs"; import yaml from "js-yaml"; const spec = yaml.load(readFileSync("openapi.yaml", "utf8")); const lines = [ `# ${spec.info.title}`, "", spec.info.description ?? "", "", ]; for (const [path, methods] of Object.entries(spec.paths)) { for (const [method, op] of Object.entries(methods)) { lines.push(`## ${method.toUpperCase()} ${path}`); lines.push(""); if (op.summary) { lines.push(op.summary); lines.push(""); } const params = op.parameters ?? []; if (params.length) { lines.push("| Name | In | Required | Description |"); lines.push("| ---- | -- | -------- | ----------- |"); for (const p of params) { lines.push( `| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.description ?? ""} |` ); } lines.push(""); } } } writeFileSync("api-reference.md", lines.join("\n")); 

Benötigte Abhängigkeit:

npm install js-yaml 

Ausführen:

node generate-api-docs.js 

Diese Variante gibt Ihnen volle Kontrolle über:

• Überschriften
• Tabellen
• Reihenfolge der Abschnitte
• Dateiaufteilung
• interne Styleguides
• zusätzliche Hinweise oder Links

Der Nachteil ist Wartung. Wenn Sie mehr OpenAPI-Features unterstützen möchten, etwa requestBody, responses, oneOf, allOf, securitySchemes oder Beispiele, müssen Sie diese selbst implementieren.

Wenn Sie abwägen, ob Sie selbst skripten oder ein Tool verwenden sollen, vergleicht die Übersicht der API-Dokumentationsgeneratoren mit Markdown-Export verschiedene Optionen.

Methode 4: Spezifikation, Dokumentation und Tests in Apidog zusammenhalten

Einmalige Konverter haben ein typisches Problem: Die Spezifikation ändert sich, aber das Markdown wird nicht neu erzeugt. Dann driftet die Dokumentation.

Apidog verfolgt einen anderen Ansatz. Sie importieren Ihre vorhandene openapi.yaml in einen Arbeitsbereich. Apidog liest Pfade, Schemas und Beispiele ein und erzeugt daraus gerenderte, gehostete API-Dokumentation. Der Import-Workflow wird im Artikel Import von Swagger oder OpenAPI und Generierung von Anfragen beschrieben. Der Weg von der Spezifikation zur veröffentlichten Referenz steht in Automatisches Generieren von API-Dokumentation aus OpenAPI.

Der praktische Vorteil liegt in zwei Punkten:

1. Generierte Referenz plus handgeschriebenes Markdown

   Die Endpunkt-Referenz kommt aus der Spezifikation. Zusätzlich können Sie eigene Markdown-Inhalte ergänzen, etwa Startseiten, Authentifizierungshinweise oder Changelog-Einträge. Die Tipps zum Erstellen von Dokumentation mit Apidog Markdown zeigen diesen Workflow.

2. Tests auf Basis derselben Spezifikation

   Die importierte Spezifikation kann auch Grundlage für Testszenarien sein. Sie erstellen Requests und Assertions gegen die definierten Endpunkte. Wenn sich die Live-API anders verhält als der Vertrag, schlagen die Tests fehl.

Zum Ausprobieren: Laden Sie Apidog herunter, importieren Sie Ihre OpenAPI-Datei und öffnen Sie die generierte Dokumentation im selben Projekt.

Wichtig: Hier geht es nicht darum, nur eine .md-Datei zu exportieren. Der Mehrwert ist, dass Spezifikation, Dokumentation und Tests nicht mehr getrennt gepflegt werden.

Automatisieren: Markdown in CI neu generieren

Ein Konverter, den Sie manuell ausführen, wird irgendwann vergessen. Besser: Regenerieren Sie Markdown automatisch, sobald sich openapi.yaml ändert.

Beispiel für GitHub Actions:

name: Generate API docs on: push: paths: - "openapi.yaml" jobs: docs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "20" - name: Convert spec to Markdown run: npx openapi-to-md openapi.yaml docs/api-reference.md - name: Commit regenerated docs run: | git config user.name "docs-bot" git config user.email "docs-bot@users.noreply.github.com" git add docs/api-reference.md git diff --staged --quiet || git commit -m "docs: regenerate API reference" git push 

Damit ist docs/api-reference.md höchstens einen Commit von der Spezifikation entfernt.

Wenn Sie Widdershins verwenden, ersetzen Sie nur den Konvertierungsschritt:

- name: Convert spec with Widdershins run: | npm install -g widdershins widdershins --omitHeader openapi.yaml -o docs/api-reference.md 

Für ein eigenes Skript:

- name: Generate custom Markdown run: | npm ci node scripts/generate-api-docs.js 

Optional: Contract-Tests in dieselbe Pipeline legen

Neu generierte Dokumentation ist nur so zuverlässig wie die Spezifikation. Deshalb lohnt es sich, Tests gegen die API in derselben Pipeline auszuführen.

Mit der Apidog CLI können Sie Testszenarien ohne UI starten:

npm install -g apidog-cli apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli 

Wenn eine Assertion fehlschlägt, beendet sich der Befehl mit einem Wert ungleich null. Dadurch schlägt auch der Build fehl.

Weitere Details stehen in der apidog run Befehlsreferenz und im vollständigen Apidog CLI-Leitfaden.

Das Muster ist einfach:

1. OpenAPI-Spezifikation ändern.
2. Markdown neu generieren.
3. Contract-Tests ausführen.
4. Nur veröffentlichen, wenn Spezifikation und API zusammenpassen.

Generiertes Markdown sauber halten

Generiertes Markdown ist selten perfekt. Diese Regeln helfen:

• Nicht manuell im generierten Abschnitt editieren.

  Änderungen werden beim nächsten Lauf überschrieben.

• Handgeschriebene Inhalte trennen.

  Legen Sie Einführung, Authentifizierung, Changelog oder Tutorials in separate Markdown-Dateien.

• Beispiele in OpenAPI pflegen.

  Viele Generatoren übernehmen example oder examples direkt aus der Spezifikation. Gute Beispiele in OpenAPI ergeben bessere Dokumentation.

• Front Matter kontrollieren.

  Wenn Ihr Zielsystem keinen Header erwartet, entfernen Sie ihn. Bei Widdershins geht das mit --omitHeader.

• Dateien sinnvoll aufteilen.

  Eine große Datei ist für eine README akzeptabel. Für Docs-Websites ist eine Aufteilung nach Tags, Ressourcen oder Produktbereichen meist besser.

• Spezifikation linten.

  Unklare Beschreibungen, fehlende Response-Schemas oder inkonsistente Parameter führen zu schlechter Ausgabe. Prüfen Sie die Quelle mit OpenAPI-Validierungstools.

Welche Methode sollten Sie wählen?

Nutzen Sie diese Entscheidungshilfe:

• Schnelle Repository-Referenz:

  Verwenden Sie openapi-to-md oder openapi-markdown.

• Statische Docs mit Codebeispielen:

  Verwenden Sie Widdershins.

• Strikter interner Styleguide:

  Schreiben Sie ein kleines Skript über die geparste Spezifikation.

• Spezifikation, Dokumentation und Tests in einem Workflow:

  Importieren Sie die Spezifikation in Apidog.

Diese Optionen schließen sich nicht aus. Viele Teams halten die Spezifikation und gehostete Dokumentation in Apidog und generieren zusätzlich Markdown in CI für das Repository.

Zusammenfassung

OpenAPI nach Markdown zu konvertieren ist einfach, wenn Sie die Rollen klar trennen: Die OpenAPI-Datei ist die Quelle, Markdown ist das generierte Artefakt.

Für eine schnelle Referenz reicht ein Einzeilen-Konverter wie openapi-to-md. Für anpassbare Docs mit Code-Tabs ist Widdershins passend. Für ein eigenes Layout schreiben Sie ein kleines Skript. Wenn Sie Spezifikation, gerenderte Dokumentation und Tests zusammenhalten möchten, importieren Sie die Spezifikation in Apidog.

Der wichtigste Schritt bleibt unabhängig vom Tool gleich: Automatisieren Sie die Generierung in CI. Dann liest Ihr Team Dokumentation, die zur tatsächlichen API passt.