DEV Community

Cover image for OpenAPI Specs automatisch in saubere Markdown-Doku konvertieren
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

OpenAPI Specs automatisch in saubere Markdown-Doku konvertieren

#api #automation #productivity #tooling

Ihre OpenAPI-Datei ist die Quelle der Wahrheit für Ihre API: Pfade, Parameter, Request-Bodies, Responses und Schemas. Für Entwickler im Alltag ist rohes YAML oder JSON aber selten das beste Lesematerial. Backend-Teams brauchen eine schnelle Endpunkt-Referenz im Repository, Frontend-Teams wollen Request- und Response-Felder im Pull Request prüfen, und technische Redakteure möchten Inhalte in Wiki- oder Docs-Systeme übernehmen, ohne Schemas abzutippen.

Testen Sie Apidog noch heute

Markdown ist dafür das praktischste Zielformat. Es funktioniert in GitHub, Confluence, Notion, Docusaurus, MkDocs, Hugo und jedem Texteditor. Die Aufgabe lautet also: Aus einer vorhandenen openapi.yaml automatisch sauberes Markdown erzeugen. Manuell ist das zu langsam und driftet beim nächsten API-Change auseinander. Automatisch generiertes Markdown bleibt dagegen Teil Ihres Release-Prozesses.

Warum Markdown aus OpenAPI generieren?

Ein OpenAPI-Dokument ist primär für Maschinen gedacht. Tools parsen es, um Clients zu generieren, Contract-Tests auszuführen, Requests zu validieren oder interaktive Dokumentation zu rendern. Diese Maschinenlesbarkeit sollten Sie beibehalten. Wenn Sie zuerst die Qualität Ihrer Spezifikation prüfen möchten, hilft der Leitfaden zu OpenAPI-Validierungstools.

Markdown löst ein anderes Problem: Es macht die API dort lesbar, wo kein OpenAPI-Renderer läuft.

Typische Einsatzfälle:

  • README.md oder /docs im Repository
  • Pull-Request-Beschreibungen für neue oder geänderte Endpunkte
  • Confluence- oder Notion-Seiten für Team-Reviews
  • Statische Dokumentationsseiten mit Docusaurus, MkDocs oder Hugo
  • Offline- oder interne Referenzdateien für Support und QA

Wichtig ist: Markdown sollte ein abgeleitetes Artefakt sein. Die OpenAPI-Spezifikation bleibt kanonisch, Markdown wird bei Änderungen neu erzeugt.

Methoden im Überblick

Es gibt keinen offiziellen OpenAPI-Befehl für Markdown-Export. In der Praxis nutzen Teams entweder Konverter, ein eigenes Skript oder eine API-Plattform.

Methode Am besten geeignet für Ergebnis
openapi-to-md / openapi-markdown Schneller Markdown-Dump ohne viel Konfiguration Einzelne Markdown-Datei oder Schematabellen
Widdershins Slate-/Docusaurus-ähnliche Dokumentation mit Code-Tabs Anpassbares Markdown mit Sprachbeispielen
Eigenes Skript Exaktes internes Layout Vollständig kontrollierte Ausgabe
Apidog Spezifikationsimport, gerenderte Docs und Tests in einem Arbeitsbereich Gehostete Dokumentation plus Markdown-Inhaltsblöcke

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
Enter fullscreen mode Exit fullscreen mode

Typischer Einsatz im Projekt:

mkdir -p docs
npx openapi-to-md openapi.yaml docs/api-reference.md
Enter fullscreen mode Exit fullscreen mode

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

git add docs/api-reference.md
git commit -m "docs: generate API reference"
Enter fullscreen mode Exit fullscreen mode

Python: openapi-markdown

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

pip install openapi-markdown
openapi2markdown openapi.yaml api-reference.md
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Basis-Konvertierung:

widdershins openapi.yaml -o api-reference.md
Enter fullscreen mode Exit fullscreen mode

Mit Sprachbeispielen:

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

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
Enter fullscreen mode Exit fullscreen mode

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"));
Enter fullscreen mode Exit fullscreen mode

Benötigte Abhängigkeit:

npm install js-yaml
Enter fullscreen mode Exit fullscreen mode

Ausführen:

node generate-api-docs.js
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Für ein eigenes Skript:

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

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)