OpenAPI till Markdown-dokumentation
Konvertera ett OpenAPI- eller Swagger-dokument till läsbar Markdown API-referensdokumentation.
OpenAPI till Markdown-dokumentation
Klistra in ett OpenAPI 3- eller Swagger 2-dokument — JSON eller YAML — och det här verktyget omvandlar det till en Markdown API-referens som du kan klistra direkt in i en README, en wikipage eller en dokumentationswebb. Varje operation blir sitt eget avsnitt, så en specifikation som bara en maskin kan läsa bekvämt blir något som en lagkamrat eller ny integratör kan skanna genom.
Utdatan innehåller en innehållsförteckning som länkar till varje grupp och slutpunkt, en parametertabell (eller en enkel lista) för sökväg, fråga, huvud- och cookie-parametrar, ett genererat förfrågningsexempel, en tabell över svarsstatuskoder med deras beskrivningar och ett exemplarresponskropp från det första matchande schemat. Gruppera slutpunkter efter tagg eller efter sitt första vägsegment, välj om förfrågningsexempel renderas som JSON-brödtext eller ett redo-att-köra curl-kommando, och välj hur djupt slutpunktstitlarna går så att resultatet passar in i ett befintligt dokument. En växel inkluderar eller hoppar över föråldrade slutpunkter; en annan dumpar varje schema under komponenter (eller Swaggers definitioner) som sitt eget avsnitt i slutet.
"$ref"-pekare inom samma fil följs automatiskt för parametrar, förfrågan/svarskroppar och scheman, så en specifikation som förlitar sig på komponenter ändå producerar fullständiga tabeller och exempel snarare än bara $ref-strängar. Referenser till annan fil eller URL lämnas ifred, eftersom ingenting här någonsin gör en nätverksbegäran. Om den genererade Markdown skulle överskrida verktygets utmatningsgräns får du ett klart meddelande istället för en frusen flik.
Allt körs lokalt i din webbläsare — din API-specifikation, som ofta beskriver system du inte vill exponera, laddas aldrig någonstans upp. Kopiera Markdown, ladda ned det som en .txt-fil eller skicka det till ett annat verktyg för att fortsätta arbeta.