how create api documentation postman
Tento výukový program vysvětluje, jak vytvořit dobře vypadající a stylovou dokumentaci s minimálním úsilím pomocí podpory dokumentace API poskytnuté nástrojem Postman Tool:
Pro jakékoli API, ať už interní nebo veřejné, je dokumentace jednou z nejdůležitějších ingrediencí pro její úspěch.
Hlavním důvodem je to, že dokumentace je způsob, jakým komunikujete se svými uživateli.
- Jak by se mělo používat vaše API?
- Jaké všechny stavové kódy jsou podporovány?
- Jaké jsou chybové kódy?
- Jaké jsou všechny typy metod vystaveny?
Všechny tyto informace jsou nezbytné, aby kdokoli mohl použít nebo implementovat API pro požadovanou potřebu.
=> Dávejte pozor na sérii jednoduchých poštovních školení zde.
jak obrátit pořadí pole v Javě
Postman poskytuje snadno použitelnou metodiku dokumentace a pro základní dokumentaci je to stejně jednoduché jako kliknutí na tlačítko v kolekci Postman a můžete získat veřejnou URL pro vaši dokumentaci API.
Co se naučíte:
Vytváření dokumentace API v Postmanu
Funkce dokumentace
Mezi hlavní funkce generátoru dokumentace Postman patří:
- Podporuje syntaxi markdown. Markdown je obecná syntaxe dokumentace, kterou byste si měli obvykle všimnout na jakémkoli projektu Github. Umožňuje zpříjemnit a usnadnit styling a formátování textu.
- Žádná konkrétní syntaxe / požadavky na vytváření dokumentace. Informace o požadavku a shromažďování se používají nejlepším způsobem ke generování dokumentace.
- Může být publikován na veřejnou adresu URL nebo na vlastní doménu (pro podnikové uživatele).
- Generuje fragmenty kódu pro volání do API v různých jazycích, jako je C #, PHP, Ruby, Python, Node atd.
Vytváření dokumentace
Generátor dokumentů Postman odkazuje na popis kolekce, složky a individuálního požadavku a porovnává je při vytváření nebo generování dokumentace pro kolekci.
Využívá různé parametry požadavku, jako jsou záhlaví, parametry řetězce dotazu, parametry formuláře a označuje použití těchto hodnot v dokumentaci požadavku.
Zde je videonávod:
Vytvořme základní kolekci se 3 požadavky pomocí stejného testovacího rozhraní API jako naše další články. Přidáme některé informace do popisu kolekce i k jednotlivým požadavkům a také vytvoříme několik příkladů požadavků a odpovědí, které budou také zachyceny při vytváření dokumentace.
Podle následujících pokynů přidejte základní informace o požadavcích a poté vytvořte dokumentaci.
# 1) Vytvořte kolekci se 3 požadavky, tj. Zaregistrujte uživatele, Přihlaste se a získejte uživatele (viz tady pro užitečné zatížení a URL API).
#dva) Nyní přidáme do sbírky nějaké informace ve formátu markdown. Markdown je standardní formát, který se používá pro téměř veškerou dokumentaci v Githubu (Další informace o markdown naleznete v tady ).
Do popisu sbírky přidáme nějaké informace ve formátu markdown, jak je uvedeno níže.
Chcete-li zobrazit náhled, jak markdown vypadá, přejděte na webový portál s otevřeným zdrojovým kódem tady.
# 3) Nyní přidáme popisy k jednotlivým požadavkům ve sbírce. Podobně jako v kolekci je formát markdown podporován i pro popisy požadavků (podrobnější informace v průvodci markdownem viz tady ).
Podívejme se na ukázku jednoho z požadavků na registraci koncového bodu uživatele (totéž lze použít i na další požadavky).
Markdown Text:
API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code
Markdown Preview:
# 4) U všech koncových bodů API pojďme zachytit nebo uložit příklad, který by použil generátor dokumentace.
Příkladem není nic jiného než ukázka požadavku na odpověď na požadavek API v úvahu. Uložení odpovědi jako příklad umožňuje generátoru dokumentace zachytit ji jako součást samotné dokumentace.
Chcete-li uložit příklad, stiskněte 'Poslat' tlačítko pro provedení požadavku a na kartě odpovědí klikněte na Uložit odpověď -> Uložit jako příklad .
Jakmile je příklad uložen, přetrvává do kolekce a lze k němu kdykoli v budoucnu přistupovat prostřednictvím Příklady odkaz v nástroji pro vytváření požadavků.
# 5) Po přidání všech výše uvedených informací se podívejme, jak vytvořit náhled dokumentace.
Otevřete možnosti kolekce a klikněte na „ Publikovat dokumenty “.
Poznámka: Zde je důležité si uvědomit, že pouze publikovaní uživatelé s Postmanem budou moci používat funkci Publikovat dokumenty na Postmanu. Registrace je zdarma, ale je třeba ji provést prostřednictvím vašeho e-mailového účtu. K registrovaným účtům se přidávají další funkce / funkce, jako je sdílení sbírek a pracovních prostorů, vytváření monitorů atd.
# 6) Jednou “ Publikovat dokumenty “Je spuštěna, otevře se karta prohlížeče s podrobnostmi o kolekci Postman (interně Postman hostuje tuto kolekci také na svých vlastních serverech kromě lokálního systému souborů uživatele).
Klikněte na 'Náhled' zobrazit dokumentaci před jejím zveřejněním.
' Publikovat sbírku Odkaz zveřejní dokumentaci na veřejně přístupnou adresu URL. Obecně se nedoporučuje publikovat rozhraní API s citlivými autorizačními informacemi k publikování na veřejnou adresu URL. Taková rozhraní API lze publikovat pomocí vlastních domén s podnikovými účty pošťáka.
# 7) Podívejme se, jak vypadá náhled dokumentace. Kliknutím na „ Náhled dokumentace “Otevírá dokumentaci v režimu náhledu, který je hostován na serverech Postman. Podívejme se, jaké různé podrobnosti jsou zachyceny v dokumentaci (Jak jsme konfigurovali na různých místech. Například , popis sbírky, popis požadavku a příklady).
Na výše uvedených 2 screenshotech můžete vidět, že všechny informace, které byly přidány do kolekce a popisy požadavků, jsou v náhledu dokumentace zachyceny stylem značkování.
jaký nástroj můžete použít k vizuální reprezentaci a analýze databáze?
Dokumentace také ve výchozím nastavení poskytuje jazykové vazby, jak je zvýrazněno, a díky tomu je mnohem jednodušší pro někoho, kdo chce přímo vytvořit požadavek API v uvedeném jazyce.
# 8) Umožňuje také provádět velmi základní úpravy stylů, jako je změna barvy pozadí, změna pozadí a barvy popředí šablon záhlaví atd. Celkově je však samotné výchozí zobrazení dostatečné k publikování opravdu dobré sady dokumentace, která zachycuje spoustu důležité podrobnosti o API.
Závěr
V tomto kurzu jsme prošli podporou dokumentace k rozhraní API poskytovanou Postmanem, pomocí které můžeme s minimálním úsilím vytvořit dobře vypadající stylovou dokumentaci.
Umožňuje také spoustu dobrých šablon a uživatelsky definovaných stylů, které lze použít na generované dokumenty, a umožňuje také publikování dokumentace na veřejnou adresu URL.
U soukromých koncových bodů API existuje také ustanovení o publikování dokumentace do vlastní domény, kterou lze konfigurovat pro podnikové účty nebo uživatele.
Další čtení = >> Jak zveřejnit smlouvu Pact na Pact Broker
=> Navštivte zde a dozvíte se Pošťák od nuly.
Doporučené čtení
- Výukový program POSTMAN: Testování API pomocí POSTMANU
- Jak a kdy používat skripty Postman Pre Request a Post Request?
- Jak používat Postman pro testování různých formátů API?
- Jak používat integraci příkazového řádku s Newmanem v Postmanu?
- Výukový program REST API: REST API Architecture And Constraints
- Vytvořte živou dokumentaci s okurkami pro soubory funkcí Specflow
- Automatizace ověřování odpovědí s tvrzeními v pošťákovi
- Kódy odezvy REST API a typy žádostí o odpočinek