OpenAPI zu Markdown-Dokumentation
Konvertiere ein OpenAPI- oder Swagger-Dokument in lesbare Markdown-API-Referenzdokumentation.
OpenAPI zu Markdown-Dokumentation
Füge ein OpenAPI 3- oder Swagger 2-Dokument im JSON- oder YAML-Format ein — dieses Tool wandelt es in eine Markdown-API-Referenz um, die du direkt in eine README-Datei, eine Wiki-Seite oder eine Dokumentationswebseite einfügen kannst. Jede Operation wird zu ihrem eigenen Abschnitt, sodass eine Spezifikation, die nur eine Maschine komfortabel lesen kann, zu etwas wird, das Teamkollegen oder neue Entwickler schnell überfliegen können.
Die Ausgabe enthält ein Inhaltsverzeichnis, das auf jede Gruppe und jeden Endpunkt verweist, eine Parametertabelle (oder eine einfache Liste) für Pfad-, Abfrage-, Header- und Cookie-Parameter, ein generiertes Anforderungsbeispiel, eine Tabelle mit Antwortkodes und ihren Beschreibungen sowie einen beispielhaften Antwortkörper aus dem ersten übereinstimmenden Schema. Gruppiere Endpunkte nach Tag oder nach ihrem ersten Pfadsegment, wähle, ob Anforderungsbeispiele als JSON-Text oder als einsatzbereiter curl-Befehl gerendert werden, und wähle, wie tief die Überschriften der Endpunkte gehen, damit das Ergebnis in ein vorhandenes Dokument passt. Ein Schalter schließt veraltete Endpunkte ein oder aus; ein anderer gibt alle Schemas unter Komponenten (oder Swagger-Definitionen) als eigene Abschnitte am Ende aus.
Zeiger vom Typ "$ref" innerhalb der gleichen Datei werden für Parameter, Anforderungs- und Antwortkörper sowie Schemas verfolgt, sodass eine Spezifikation, die sich auf Komponenten stützt, immer noch vollständige Tabellen und Beispiele statt nur $ref-Strings erzeugt. Verweise auf andere Dateien oder URLs werden ignoriert, da dieses Tool nie eine Netzwerkanfrage stellt. Wenn die generierte Markdown die Ausgabegrenzen des Tools überschreiten würde, erhältst du eine klare Fehlermeldung statt eines eingefrorenen Tabs.
Alles läuft lokal in deinem Browser — deine API-Spezifikation, die oft Systeme beschreibt, die du nicht freilegen möchtest, wird niemals hochgeladen. Kopiere das Markdown, lade es als .txt-Datei herunter oder sende es an ein anderes Tool zum Weiterarbeiten.