OpenAPI naar Markdown-documentatie
Converteer een OpenAPI- of Swagger-document naar leesbare Markdown API-referentiedocumentatie.
OpenAPI naar Markdown-documentatie
Plak een OpenAPI 3- of Swagger 2-document — JSON of YAML — en deze tool zet het om in een Markdown API-verwijzing die je rechtstreeks in een README, wikipagina of documentatiesite kunt plaatsen. Elke bewerking wordt zijn eigen sectie, zodat een specificatie die alleen een machine comfortabel kan lezen, iets wordt dat teamgenoten of nieuwe integrators kunnen scannen.
De uitvoer bevat een inhoudsopgave die linkt naar elke groep en eindpunt, een parametertabel (of een eenvoudige lijst) voor pad-, query-, header- en cookie-parameters, een gegenereerd verzoeklichaammonster, een tabel met responsstatuscodes met hun beschrijvingen, en een voorbeeldresponskern uit het eerste overeenkomende schema. Groepeer eindpunten op tag of op hun eerste padsegment, kies of verzoekmonsters weergegeven worden als JSON-lichaam of als klaar-voor-gebruik curl-opdracht, en kies hoe diep de eindpuntkoppen gaan zodat het resultaat in een bestaand document past. Een schakelaar neemt verouderde eindpunten op of overslaat deze; een ander dumpt elk schema onder componenten (of Swagger's definities) als zijn eigen sectie aan het einde.
"$ref"-wijzers binnen hetzelfde bestand worden automatisch gevolgd voor parameters, verzoek- en responselichamen, en schema's, zodat een specificatie die op componenten leunt, volledige tabellen en monsters produceert in plaats van onbewerkte $ref-tekenreeksen. Verwijzingen naar een ander bestand of URL worden genegeerd, aangezien hier nooit een netwerkaanvraag wordt gedaan. Als de gegenereerde Markdown zou overschrijden, krijg je een duidelijk bericht in plaats van een bevroren tabblad.
Alles draait lokaal in uw browser — uw API-specificatie, die vaak systemen beschrijft die u niet wilt blootstellen, wordt nooit ergens geüpload. Kopieer de Markdown, download het als .txt-bestand of stuur het naar een ander hulpmiddel om mee door te werken.