OpenAPI Specs automatisch in saubere Markdown-Doku konvertieren

Ihre OpenAPI-Datei ist die Quelle der Wahrheit für Ihre API. Sie listet jeden Pfad, jeden Parameter und jede Antwortstruktur auf. Das Problem ist, dass fast niemand in Ihrem Team rohes YAML oder JSON lesen möchte. Ein Backend-Ingenieur wünscht sich eine schnelle Endpunkt-Referenz im Repository. Ein Frontend-Entwickler möchte eine Tabelle mit Anforderungsfeldern, die er in einem Pull Request überblicken kann. Ein technischer Redakteur möchte etwas, das er in ein Wiki einfügen kann, ohne das gesamte Schema neu tippen zu müssen.

Markdown ist das Format, das all diesen Lesern gerecht wird. Es wird auf GitHub, in Confluence, in einem Generator für statische Websites und in einem einfachen Texteditor gerendert. Die wiederkehrende Aufgabe ist also diese: Nehmen Sie eine bereits vorhandene openapi.yaml und verwandeln Sie sie in sauberes Markdown, das Menschen tatsächlich öffnen. Dies manuell zu tun, ist langsam und es weicht ab, sobald jemand einen Endpunkt hinzufügt. Es automatisch zu tun, ist die einzige Version, die den Kontakt mit einem echten Release-Zyklus überlebt.

Warum überhaupt Markdown aus OpenAPI generieren?

Ein OpenAPI-Dokument ist für Maschinen konzipiert. Tools parsen es, um Clients zu generieren, Vertragstests durchzuführen, Anfragen zu validieren und interaktive Dokumentationen zu rendern. Diese Maschinenlesbarkeit ist der Kernpunkt und es lohnt sich, sie zu schützen. Wenn Sie eine Auffrischung darüber wünschen, wie die Spezifikation selbst korrekt gehalten wird, behandelt der Leitfaden zu den OpenAPI-Validierungstools das Linting, bevor Sie überhaupt etwas daraus generieren.

Markdown löst ein anderes Problem: die Verbreitung an Menschen an Orten, die keinen OpenAPI-Renderer ausführen. Einige konkrete Fälle treten immer wieder auf.

• Ein README.md oder /docs-Ordner im Repository, damit ein neuer Mitwirkender die Endpunktliste sieht, ohne die Codebasis verlassen zu müssen.
• Eine Pull-Request-Beschreibung, die zeigen muss, was ein neuer Endpunkt akzeptiert und zurückgibt.
• Eine Confluence- oder Notion-Seite, auf der das gesamte Team, einschließlich Nicht-Ingenieuren, den Vertrag überprüft.
• Eine statische Dokumentationsseite, die mit Docusaurus, MkDocs oder Hugo erstellt wurde, die alle Markdown als Eingabe verwenden.

Das Schlüsselwort ist automatisch. Eine Markdown-Datei, die Sie einmal schreiben und vergessen, ist beim nächsten Sprint bereits falsch. Eine Markdown-Datei, die bei jeder Änderung aus der Spezifikation neu generiert wird, bleibt dem Vertrag kostenlos treu. Das ist der Unterschied zwischen Dokumentationen, denen die Leute vertrauen, und Dokumentationen, die die Leute ignorieren lernen.

Die Konvertierungsmethoden, von schnell bis kugelsicher

Es gibt keinen einzigen offiziellen Befehl, der mit OpenAPI geliefert wird, um Markdown zu erzeugen. Stattdessen gibt es ein kleines Ökosystem von Konvertern sowie die in API-Plattformen integrierten Dokumentations-Engines. Hier ist die Übersicht, grob geordnet nach dem Aufwand, den jede Einrichtung erfordert.

Wählen Sie basierend darauf, wie viel Kontrolle Sie benötigen und wo die Ausgabe landen soll. Die nächsten Abschnitte zeigen die einzelnen Methoden in Aktion.

Methode 1: Ein einzeiliger Open-Source-Konverter

Der schnellste Weg ist ein dedizierter Konverter. Zwei bekannte decken die Node- und Python-Welten ab.

Für ein Node-Projekt nimmt openapi-to-md ein v2- oder v3-Dokument in YAML oder JSON entgegen und schreibt eine strukturierte Markdown-Datei. Sie können es ohne globale Installation ausführen:

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

Für eine Python-Toolchain erledigt openapi-markdown dieselbe Aufgabe mit einer pip-Installation und einem einzigen Befehl:

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

Beide lesen die Spezifikation, durchlaufen jeden Pfad und jedes Schema und erzeugen eine Markdown-Datei mit Überschriften pro Endpunkt und Tabellen für Parameter und Antworten. Das Argument für die Ausgabedatei ist bei einigen dieser Tools optional; lassen Sie es weg, und sie verwenden standardmäßig den Eingabenamen mit der Erweiterung .md. Das reicht für eine Repository-Referenz, die Sie bei Bedarf neu generieren können.

Der Kompromiss bei den schnellen Konvertern ist die Kontrolle über das Layout. Sie erhalten deren Struktur, nicht Ihre eigene. Wenn ihre Standardtabellen der Art und Weise entsprechen, wie Ihr Team Dokumentationen liest, sind Sie mit einer Zeile fertig. Wenn Sie Codebeispiele in fünf Sprachen oder eine bestimmte Reihenfolge der Abschnitte benötigen, möchten Sie die nächste Methode.

Methode 2: Widdershins für anpassbare Dokumentation mit Codebeispielen

Widdershins ist das etablierte Node-Tool, um eine OpenAPI- oder Swagger-Datei in Slate-kompatibles Markdown umzuwandeln. Es ist die richtige Wahl, wenn Sie Sprachcode-Tabs und eine anpassbare Vorlage wünschen und wenn das Markdown einen Generator für statische Websites wie Docusaurus oder MkDocs speist.

Installieren Sie es und führen Sie die grundlegende Konvertierung aus:

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

Fügen Sie Codebeispiel-Sprachen hinzu und lassen Sie den Front-Matter-Header weg, wenn Sie die Ausgabe an eine Stelle weiterleiten, die ihren eigenen hinzufügt:

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

Widdershins verwendet ein Vorlagensystem, sodass Sie das Layout jedes Abschnitts überschreiben können, anstatt die Standardeinstellung zu akzeptieren. Das macht es zur Brücke zwischen einem Roh-Dump und einer vollständig von Hand erstellten Dokumentationsseite. Der Preis ist, dass Sie nun eine Vorlage und einen Build-Schritt besitzen, was für ein Dokumentations-Repository in Ordnung, aber für eine schnelle README übertrieben ist.

Methode 3: Ein benutzerdefiniertes Skript, wenn Sie ein exaktes Layout benötigen

Manchmal erzeugt keiner der vorgefertigten Konverter die gewünschte Form. Vielleicht benötigen Sie eine Markdown-Datei pro Tag, oder einen kompakten Endpunktindex, oder Schematabellen, die einem internen Styleguide entsprechen. In diesem Fall parsen Sie die Spezifikation selbst und erstellen die Ausgabe mithilfe einer Vorlage. Die Spezifikation ist nur strukturierte Daten, daher ist dies weniger Aufwand, als es klingt.

Eine minimale Node-Version, die jede Operation auflistet, sieht so aus:

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("");
    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"));

Das sind etwa vierzig Zeilen für die volle Kontrolle über die Ausgabe. Sie bestimmen die Überschriften, die Tabellenspalten, die Dateiaufteilung. Der Nachteil ist der Wartungsaufwand: Wenn die von Ihnen verwendete OpenAPI-Version eine Funktion hinzufügt, muss Ihr Skript diese lernen. Für einen stabilen internen Stil ist dieser Kompromiss in der Regel lohnenswert. Für eine breite Spezifikationsabdeckung sollten Sie stattdessen auf einen gewarteten Konverter zurückgreifen. Wenn Sie abwägen, ob Sie dies selbst skripten oder kaufen sollen, vergleicht die Übersicht der API-Dokumentationsgeneratoren mit Markdown-Export die gewarteten Optionen nebeneinander.

Methode 4: Spezifikation, Dokumentation und Tests in Apidog zusammenhalten

Die oben genannten Konverter haben alle einen blinden Fleck. Sie verwandeln eine Spezifikation in Markdown, und dann driften die beiden auseinander. Jemand bearbeitet die API, vergisst, den Konverter erneut auszuführen, und das Markdown lügt. Die Lösung besteht darin, die Spezifikation nicht mehr als eigenständige Datei zu behandeln, sondern als Teil eines Arbeitsbereichs, in dem sich Dokumentationen und Tests mit ihr aktualisieren.

Das ist das Modell, das Apidog verwendet. Sie importieren Ihre vorhandene openapi.yaml, und Apidog liest jeden Pfad, jedes Schema und jedes Beispiel in ein Projekt ein. Von dort erhalten Sie gerenderte, gehostete API-Dokumentation, die direkt aus der importierten Spezifikation generiert wird, ohne separaten Build-Schritt. Der vollständige Import-Workflow wird unter Import von Swagger oder OpenAPI und Generierung von Anfragen behandelt, und der Weg von der Spezifikation zur veröffentlichten Referenz unter Automatisches Generieren von API-Dokumentation aus OpenAPI.

Zwei Dinge unterscheiden dies von einem Einmal-Konverter.

• Erstens unterstützt die Dokumentation eigene Markdown-Inhaltsblöcke. Die generierte Endpunkt-Referenz stammt aus der Spezifikation, und Sie legen handgeschriebenes Markdown darum herum: eine Startseite, Authentifizierungshinweise, Changelog-Einträge. Die Tipps zum Erstellen von Dokumentation mit Apidog Markdown führen durch diese Autorenseite. Sie wählen also nicht zwischen generierter und geschriebener Dokumentation; Sie erhalten beides an einem Ort.
• Zweitens wird dieselbe importierte Spezifikation zur Grundlage für Testszenarien. Sie erstellen Anfragen und Assertions gegen die von der Spezifikation definierten Endpunkte und führen diese dann aus, um zu beweisen, dass die Live-API immer noch dem Vertrag entspricht, der Ihre Dokumentation erstellt hat. Das schließt den Drift-Kreislauf: Wenn die API sich ändert und den Vertrag bricht, schlagen die Tests fehl, und Sie wissen, dass die Dokumentation veraltet ist, bevor es ein Leser tut.

Um mitzumachen, laden Sie Apidog herunter, importieren Sie eine Spezifikation und öffnen Sie die generierten Dokumente im selben Projekt. Es geht nicht darum, dass Apidog eine .md-Datei auf die Festplatte schreibt. Es geht darum, dass die Spezifikation, die menschenlesbaren Dokumente und die Tests, die beide ehrlich halten, nicht länger drei getrennte Dateien sind.

Automatisch machen: Markdown in CI neu generieren

Ein Konverter, den Sie manuell ausführen, ist ein Konverter, den Sie vergessen. Der volle Wert der Generierung von Markdown aus OpenAPI zeigt sich nur, wenn die Generierung bei jeder Änderung automatisch abläuft. Das Muster ist einfach: Bei jedem Push, der die Spezifikation betrifft, generieren Sie das Markdown neu und committen es zurück oder veröffentlichen es.

Hier ist ein GitHub Actions-Job, der die Referenz neu generiert, sobald sich openapi.yaml ändert:

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

Jetzt kann das Markdown nie mehr als einen Commit von der Spezifikation abweichen. Dieselbe Idee funktioniert in GitLab CI oder jedem Runner mit Node oder Python; tauschen Sie den Konvertierungsschritt gegen widdershins oder Ihr Skript aus.

Es gibt noch ein weiteres Element, das es wert ist, integriert zu werden. Neu generierte Dokumente sind nur vertrauenswürdig, wenn die Spezifikation, aus der sie stammen, immer noch korrekt ist. Dort verdient ein Kommandozeilen-Testlauf seinen Platz in derselben Pipeline. Das Apidog CLI führt die von Ihnen erstellten Testszenarien gegen Ihre importierte Spezifikation ohne Benutzeroberfläche mit einem einzigen Befehl aus:

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

Es wird mit einem von Null verschiedenen Wert beendet, wenn eine Assertion fehlschlägt, was den Build fehlschlagen lässt, was Sie daran hindert, Dokumente zu veröffentlichen, die eine API beschreiben, die sich nicht mehr so verhält. Die vollständige Flag-Übersicht finden Sie in der apidog run Befehlsreferenz, und die umfassendere Pipeline-Einrichtung im Apidog CLI vollständigen Leitfaden. Kombinieren Sie die Dokumentationsgenerierung mit einem Vertragstest, und die beiden verstärken sich gegenseitig: Die Spezifikation erzeugt die Dokumentation, und der Test beweist die Spezifikation.

Bereinigen des generierten Markdowns

Generiertes Markdown ist selten beim ersten Durchgang perfekt. Einige Gewohnheiten halten es lesbar.

• Entfernen Sie den automatisch generierten Front Matter, wenn der Ziel-Renderer ihn nicht möchte. Widdershins tut dies mit --omitHeader; bei anderen Tools funktioniert ein schnelles sed über den Dateianfang.
• Entscheiden Sie sich für eine Dateiaufteilung. Eine riesige Markdown-Datei ist für eine README in Ordnung. Für eine Dokumentationsseite teilen Sie nach Tag oder Ressource auf, damit jede Seite kurz ist.
• Halten Sie Beispiele real. Die meisten Konverter ziehen Beispielwerte direkt aus der Spezifikation, sodass die Qualität Ihrer generierten Dokumente die Qualität Ihrer examples in OpenAPI widerspiegelt. Bessere Beispiele hinein, bessere Dokumente heraus.
• Neu generieren, nicht manuell bearbeiten. Sobald Sie generiertes Markdown manuell bearbeiten, überschreibt die nächste Konvertierung Ihre Änderungen. Legen Sie handgeschriebene Inhalte in separate Dateien und lassen Sie den Generator nur den Referenzabschnitt besitzen.

Wenn Ihre Spezifikation selbst unordentlich ist, beheben Sie dies an der Quelle. Sauberere Spezifikationen führen zu saubereren Dokumenten, und der Beitrag zu den OpenAPI-Validierungstools zeigt, wie man nach Lücken lint, die zu unschöner Ausgabe führen.

Die richtige Methode für Ihr Team auswählen

Passen Sie das Tool daran an, wohin das Markdown gehen soll und wie viel Kontrolle Sie benötigen.

• Sie möchten eine Repository-Referenz mit einem Befehl und sind nicht wählerisch bezüglich des Layouts: Verwenden Sie openapi-to-md oder openapi-markdown.
• Sie erstellen eine Dokumentationsseite mit Codebeispielen und möchten eine anpassbare Vorlage: Verwenden Sie Widdershins.
• Sie haben einen internen Styleguide, den die Konverter nicht erfüllen können: Schreiben Sie ein kleines Skript über die geparste Spezifikation.
• Sie möchten die Dokumentation, die Spezifikation und die Tests, die sie ehrlich halten, in einem Arbeitsbereich haben, mit gehosteter Ausgabe und ohne separaten Build, den Sie betreuen müssen: Importieren Sie die Spezifikation in Apidog.

Diese schließen sich nicht gegenseitig aus. Viele Teams verwenden Apidog als Quelle der Wahrheit für die Spezifikation und ihre gehostete Dokumentation und führen dann einen Konverter in CI aus, um eine Markdown-Referenz zur Offline-Lektüre in das Repository zu legen. Die Spezifikation bleibt kanonisch; das Markdown ist ein abgeleitetes Artefakt, das Sie jederzeit neu generieren können.

Zusammenfassung

Die Konvertierung von OpenAPI nach Markdown ist ein gelöstes Problem, solange Sie die Spezifikation als Quelle und das Markdown als abgeleitete Datei behandeln. Für eine schnelle Repository-Referenz leistet ein Einzeilen-Konverter wie openapi-to-md gute Dienste. Für eine anpassbare Dokumentationsseite bietet Widdershins Vorlagen und Code-Tabs. Für ein exaktes internes Layout ist ein kurzes Skript über die geparste Spezifikation die beste Wahl. Und wenn Sie die Spezifikation, die gerenderte Dokumentation und die Tests, die sie synchron halten, zusammenführen möchten, beseitigt der Import in Apidog die Abweichungen, die jeden anderen Ansatz im Laufe der Zeit zunichtemachen.

Was auch immer Sie wählen, automatisieren Sie es. Generieren Sie das Markdown in CI bei jeder Spezifikationsänderung, und die Dokumentation, die Ihr Team liest, wird immer der API entsprechen, die sie beschreibt.