Documentație OpenAPI în Markdown
Convertiți o specificație OpenAPI sau Swagger într-o documentație de referință API în Markdown.
Documentație OpenAPI în Markdown
Lipiți o specificație OpenAPI 3 sau Swagger 2 — JSON sau YAML — și acest instrument o transformă într-o referință de API în Markdown pe care o puteți plasa direct într-un README, pe o pagină wiki sau pe un site de documentație. Fiecare operație devine propria sa secțiune, deci o specificație pe care doar o mașină ar putea să o citească confortabil devine ceva pe care un coleg sau un nou integrator poate să o exploreze.
Rezultatul include un tabel de conținuturi care se leagă la fiecare grup și endpoint, un tabel de parametri (sau o listă simplă) pentru parametrii de cale, interogare, antet și cookie, un eșantion de corp de cerere generat, un tabel de coduri de răspuns cu descrierile acestora, și un corp de răspuns exemplu din prima schemă potrivită. Grupați endpoint-urile după etichetă sau după primul segment al căii acestora, alegeți dacă eșantioanele de cerere se redă ca un corp JSON sau ca o comandă curl gata de rulare, și selectați cât de adânci sunt titlurile endpoint-ului, astfel încât rezultatul să se potrivească într-un document existent. O butonă include sau omite endpoint-urile depășite; o alta descarcă fiecare schemă sub componente (sau definițiile Swagger) ca propria secțiune la sfârșitul documentului.
Pointeriii "$ref" din același fișier sunt urmăriți pentru parametri, corpuri de cerere și răspuns, și scheme, deci o specificație care se bazează pe componente produce tabele și eșantioane complete în loc de șiruri $ref goale. Referințele către alt fișier sau URL sunt lăsate în pace, deoarece nimic aici nu face niciodată o cerere de rețea. Dacă Markdown-ul generat ar depăși limita de ieșire a instrumentului, obțineți un mesaj clar în loc de o filă blocată.
Totul rulează local în browserul dvs. — specificația dvs. API, care descrie adesea sisteme pe care nu doriți să le expuneți, nu este niciodată încărcată nicaieri. Copiați Markdown-ul, descărcați-l ca fișier .txt sau trimiteți-l unui alt instrument pentru a continua lucrul.