how create api documentation postman
V tomto výučbe sa dozviete, ako vytvoriť dobre vyzerajúcu štýlovú dokumentáciu s minimálnym úsilím pomocou podpory dokumentácie API poskytnutej nástrojom Postman Tool:
Pre každé API, či už interné alebo verejné, je dokumentácia jednou z najdôležitejších ingrediencií pre jeho úspech.
Hlavným dôvodom je to, že dokumentácia je spôsob komunikácie s používateľmi.
- Ako by sa malo používať vaše API?
- Aké všetky stavové kódy sú podporované?
- Aké sú chybové kódy?
- Čo sú všetky typy metód vystavené?
Všetky tieto informácie sú nevyhnutné pre to, aby ktokoľvek mohol použiť alebo implementovať API pre požadovanú potrebu.
=> Dajte si tu pozor na sériu jednoduchých poštárov.
čo je nesúlad kľúčov zabezpečenia siete
Postman poskytuje ľahko použiteľnú metodiku dokumentácie a pre základnú dokumentáciu je to také jednoduché ako kliknutie na tlačidlo v zbierke Postman a môžete získať verejnú adresu URL svojej dokumentácie API.
Čo sa dozviete:
Vytváranie dokumentácie API v službe Postman
Funkcie dokumentácie
Hlavné vlastnosti generátora dokumentácie Postman zahŕňajú:
- Podporuje syntax značky. Markdown je všeobecná syntax dokumentácie, ktorú by ste si mali zvyčajne všimnúť pri akomkoľvek projekte Github. Umožňuje vám oboznámiť sa a uľahčiť tvarovanie a formátovanie textu.
- Žiadna konkrétna syntax / požiadavky na vytvorenie dokumentácie. Informácie o požiadavkách a zhromažďovaní sa využívajú najlepším spôsobom na generovanie dokumentácie.
- Môže byť zverejnený na verejnej adrese URL alebo na vlastnej doméne (pre podnikových používateľov).
- Generuje úryvky kódu na uskutočňovanie hovorov na API v rôznych jazykoch, ako sú C #, PHP, Ruby, Python, Node atď.
Vytváranie dokumentácie
Generátor dokumentov Postman odkazuje na zbierku, popis priečinka a jednotlivých požiadaviek a zhromažďuje ich pri vytváraní alebo generovaní dokumentácie pre zbierku.
Využíva rôzne parametre požiadavky, ako sú Hlavičky, Parametre reťazca dopytu, Parametre formulára a označuje použitie týchto hodnôt v dokumentácii požiadavky.
Tu je videonávod:
Vytvorme základnú kolekciu s 3 požiadavkami pomocou rovnakého testovacieho rozhrania API ako naše ďalšie články. Doplníme niektoré informácie do popisu zbierky aj k jednotlivým požiadavkám a tiež vytvoríme niekoľko vzorových požiadaviek a odpovedí, ktoré sa zachytia aj pri vytváraní dokumentácie.
Podľa nasledujúcich pokynov môžete pridať základné informácie o požiadavkách a potom vytvoriť dokumentáciu.
# 1) Vytvorte kolekciu s 3 požiadavkami, t. J. Zaregistrujte sa, prihláste sa a získajte používateľa (viď tu pre užitočné dáta a URL API).
#dva) Teraz pridajme do zbierky nejaké informácie vo formáte markdown. Markdown je štandardný formát, ktorý sa používa takmer vo všetkej dokumentácii v Github (Viac informácií o markdown nájdete v tu ).
Do popisu zbierky pridáme nejaké informácie vo formáte markdown, ako je uvedené nižšie.
Ak chcete zobraziť ukážku toho, ako markdown vyzerá, navštívte webový portál s otvoreným zdrojovým kódom tu.
# 3) Teraz pridáme popisy k jednotlivým požiadavkám v zbierke. Formát zbierky je podobne ako v kolekcii podporovaný aj pre popisy požiadaviek (podrobnejšie informácie o sprievodcovi zmenšením nájdete na tu ).
Pozrime sa na ukážku jednej z požiadaviek na koncový bod registrácie používateľa (to isté sa dá aplikovať aj na ďalšie žiadosti).
Text zľavy:
API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code
Ukážka Markdown:
# 4) Pre všetky koncové body API poďme zachytiť alebo uložiť príklad, ktorý by použil generátor dokumentácie.
Príkladom nie je nič iné ako vzorová požiadavka-odpoveď na požiadavku API. Uloženie odpovede ako príkladu umožňuje generátoru dokumentácie zachytiť ju ako súčasť samotnej dokumentácie.
Ak chcete uložiť príklad, stlačte „Odoslať“ na vykonanie požiadavky a na karte odpovedí kliknite na Uložiť odpoveď -> Uložiť ako príklad .
Po uložení sa príklad uchová v zbierke a je k nemu prístup kedykoľvek prostredníctvom aplikácie Príklady odkaz v nástroji na tvorbu požiadaviek.
# 5) Po pridaní všetkých vyššie uvedených informácií sa pozrime, ako vytvoriť ukážku dokumentácie.
Otvorte možnosti zbierky a kliknite na „ Publikovať dokumenty “.
Poznámka: Tu je dôležité si uvedomiť, že funkciu Zverejniť dokumenty v službe Postman budú môcť používať iba registrovaní používatelia služby Postman. Registrácia je bezplatná, ale musí sa vykonať prostredníctvom vášho e-mailového účtu. K registrovaným účtom sa pridávajú ďalšie možnosti / funkcie, ako je zdieľanie zbierok a pracovných priestorov, vytváranie monitorov atď.
# 6) Raz “ Publikovať dokumenty ”Sa vykoná, otvorí sa karta prehliadača s podrobnosťami zbierky Postman (interne Postman hostuje túto kolekciu okrem svojich lokálnych systémov súborov aj na svojich vlastných serveroch).
Kliknite na 'Náhľad' aby ste si pozreli dokumentáciu pred jej zverejnením.
„ Publikovať zbierku Odkaz zverejní dokumentáciu na verejne prístupnú adresu URL. Spravidla sa neodporúča zverejňovať rozhrania API s citlivými autorizačnými informáciami na zverejnenie na verejnej adrese URL. Takéto rozhrania API je možné publikovať pomocou vlastných domén s podnikovými účtami poštára.
# 7) Pozrime sa, ako vyzerá ukážka dokumentácie. Kliknutím na „ Náhľad dokumentácie “Otvára dokumentáciu v režime náhľadu, ktorý je hostený na serveroch spoločnosti Postman. Pozrime sa, aké rôzne podrobnosti sú zachytené v dokumentácii (konfigurovali sme na rôznych miestach. Napríklad , popis zbierky, popis žiadosti a príklady).
Na vyššie uvedených dvoch snímkach obrazovky môžete vidieť, že všetky informácie, ktoré boli pridané do kolekcie a popisy požiadaviek, sú v ukážke dokumentácie zachytené štýlom zmenšenia.
vážený graf susedstva c ++
Dokumentácia tiež predvolene poskytuje jazykové väzby tak, ako sú zvýraznené, a tým je oveľa jednoduchšie pre niekoho, kto chce priamo zadať požiadavku API v uvedenom jazyku.
# 8) Umožňuje vám tiež vykonať veľmi základné úpravy štýlov, ako je zmena farby pozadia, zmena farby pozadia a popredia šablón hlavičiek atď. Celkovo však samotné predvolené zobrazenie stačí na zverejnenie skutočne dobrej sady dokumentácie, ktorá zachytáva množstvo dôležité podrobnosti o API.
Záver
V tomto tutoriáli sme si prešli podporu dokumentácie API, ktorú poskytuje Postman, pomocou ktorej môžeme s minimálnym úsilím vytvoriť dobre vyzerajúcu štýlovú dokumentáciu.
Umožňuje tiež veľa dobrých šablón a používateľom definovaný štýl, ktorý je možné použiť na vygenerované dokumenty, a umožňuje publikovanie dokumentácie aj na verejnú adresu URL.
Pre súkromné koncové body API existuje aj ustanovenie o publikovaní dokumentácie na vlastnú doménu, ktorú je možné nakonfigurovať pre podnikové účty alebo používateľov.
Ďalšie čítanie = >> Ako zverejniť Paktovú zmluvu pre Pakt Broker
=> Navštívte tu a dozviete sa Poštára od nuly.
Odporúčané čítanie
- Výukový program POSTMAN: Testovanie API pomocou programu POSTMAN
- Ako a kedy používať skripty Postman Pre Request a Post Request?
- Ako používať Postman na testovanie rôznych formátov API?
- Ako používať integráciu príkazového riadku s Newmanom v Postmani?
- Výukový program Rest API: REST API Architecture and Constraints
- Vytvorte živú dokumentáciu pomocou funkcie Pickles pre súbory funkcií Specflow
- Automatizácia overovania odpovedí s tvrdeniami v poštovom doručovateľovi
- Kódy odozvy Rest API a typy žiadostí o odpočinok