OpenAPI u dokumentaciju Markdown
Pretvorite OpenAPI ili Swagger dokument u čitljivu Markdown referentnu dokumentaciju API-ja.
OpenAPI u dokumentaciju Markdown
Zalijepite OpenAPI 3 ili Swagger 2 dokument — JSON ili YAML — i ovaj alat ga pretvara u Markdown referentnu dokumentaciju API-ja koju možete direktno uključiti u README, wiki stranicu ili dokumente. Svaka operacija postaje vlastiti odjeljak, pa specifikacija koju može čitati samo stroj postaje nešto što kolega ili novi integrator može brzo pregledati.
Ishodak uključuje sadržaj s linkovima na svaku grupu i krajnju točku, tablicu parametara (ili obični popis) za putanju, upit, zaglavlje i cookie parametre, generirani uzorak tijela zahtjeva, tablicu kodova odgovora s opisima, i primjer tijela odgovora iz prve podudarajuće sheme. Grupirajte krajnje točke po oznaci ili po prvom segmentu njihove putanje, odaberite da li se uzorci zahtjeva prikazuju kao JSON tijelo ili kao sprema curl naredba, te odaberite koliko duboko zaglavlja krajnje točke idu kako bi rezultat ugnjezdili u postojeći dokument. Jedan gumb uključuje ili preskače zastarjele krajnje točke; drugi ispisuje svaku shemu pod komponentama (ili Swagger-ove definicije) kao vlastiti odjeljak na kraju.
Reference "$ref" unutar iste datoteke se prate za parametre, tijela zahtjeva i odgovora, te sheme, pa specifikacija koja se oslanja na komponente i dalje proizvodi pune tablice i uzorke umjesto golih $ref stringova. Reference u drugu datoteku ili URL ostaju netaknute jer ovdje se nikada ne pravi mrežna zahtjeva. Ako generirani Markdown premašuje graničnu vrijednost ishodišta alata dobijate jasnu poruku umjesto zamrznutog separatora.
Svega se pokrenuti lokalno u vašem pregledniku — vaša specifikacija API-ja, koja često opisuje sisteme koje ne želite izložiti, nikada se ne šalje nikamo. Kopirajte Markdown, preuzmite ga kao .txt datoteku ili ga pošaljite drugom alatu da nastavite raditi na njemu.