OpenAPI na dokumentáciu Markdown
Premeniť dokument OpenAPI alebo Swagger na čitateľnú referenčnú dokumentáciu API v Markdown.
OpenAPI na dokumentáciu Markdown
Vložte dokument OpenAPI 3 alebo Swagger 2 — JSON alebo YAML — a tento nástroj ho premení na referenčnú dokumentáciu API v Markdown, ktorú môžete vložiť priamo do README, stránky wiki alebo webu dokumentácie. Každá operácia sa stane vlastnou sekciou, takže špecifikácia, ktorú by mohla ľahko čítať iba máquina, sa stane niečím, čo si kolegovia alebo noví integrátoři môžu rýchlo prehliadnuť.
Výstup obsahuje obsah s odkazmi na jednotlivé skupiny a koncové body, tabuľku parametrov (alebo jednoduchý zoznam) pre parametre cesty, query, záhlavia a cookies, vygenerovanú ukážku tela požiadavky, tabuľku kódov odpovedí s ich opisom a príkladnú odpoveď z prvej zodpovedajúcej schémy. Zoskupte koncové body podľa tagu alebo podľa prvého segmentu ich cesty, vyberte si, či sa ukážky požiadavok majú zobraziť ako telo JSON alebo ako spustiteľný príkaz curl, a nastavte hĺbku nadpisov koncových bodov tak, aby bol výsledok vnorený do existujúceho dokumentu. Jeden prepínač zahrňuje alebo preskakuje zastarané koncové body; ďalší vypíše každú schému pod komponentami ako vlastnú sekciu na konci.
Odkazy "$ref" v rámci rovnakého súboru sa automaticky sledujú pre parametre, telesá požiadavok a odpovedí a schémy, takže špecifikácia, ktorá sa spolieha na komponenty, stále produkuje úplné tabuľky a ukážky namiesto holých reťazcov $ref. Odkazy na iný súbor alebo URL sú ponechané bez zmeny, pretože tento nástroj nikdy nedosahuje mimo prehliadač. Ak by vygenerovaný Markdown prekročil limit výstupu nástroja, zobrazí sa vám jasná správa namiesto zasekaného záložky.
Všetko sa spúšťa lokálne vo vašom prehliadači — vaša špecifikácia API, ktorá často popisuje systémy, ktoré nechcete odhaliť, nie je nikdy nikam nahravaná. Skopírujte Markdown, stiahnite si ho ako súbor .txt alebo ho pošlite ďalšiemu nástroju, aby ste na ňom mohli ďalej pracovať.