Meni

Kako stvoriti API dokumentaciju u poštaru?

how create api documentation postman

Isprobajte Naš Instrument Za Uklanjanje Problema

Ovaj vodič objašnjava kako stvoriti dobro izgledajuću, stiliziranu dokumentaciju uz minimalne napore koristeći API podršku za dokumentaciju koju pruža Alat za poštare:

Za bilo koji API, bilo interni ili javni, dokumentacija je jedan od najvažnijih sastojaka za njegov uspjeh.

Glavni razlog tome je što je dokumentacija način na koji komunicirate sa svojim korisnicima.

  • Kako treba koristiti vaš API?
  • Koji su svi statusni kodovi podržani?
  • Koji su kodovi pogrešaka?
  • Koje su sve vrste metoda izložene?

Sve su ove informacije potrebne svima da bi koristili ili implementirali API za željenu potrebu.

=> Ovdje pripazite na jednostavnu seriju treninga za poštare.

Poštar - Izrada API dokumentacije

java nasuprot c ++

Postman nudi metodologiju dokumentacije koja se lako koristi, a za osnovnu dokumentaciju jednostavna je poput klika na gumb kroz zbirku Poštara i možete dobiti javni URL za svoju API dokumentaciju.

Što ćete naučiti:

Stvaranje API dokumentacije u poštaru

Značajke dokumentacije

Istaknute značajke generatora dokumentacije Poštara uključuju:

  • Podržava sintaksu označavanja. Markdown je generička sintaksa dokumentacije, koju biste obično trebali primijetiti na bilo kojem Github projektu. Omogućuje styling i oblikovanje teksta što je više poznato i lakše.
  • Nema specifične sintakse / zahtjeva za kreiranje dokumentacije. Informacije o zahtjevima i prikupljanju koriste se na najbolji način za generiranje dokumentacije.
  • Može se objaviti na javnom URL-u ili na prilagođenoj domeni (za poslovne korisnike).
  • Generira isječke koda za upućivanje poziva API-ju na različitim jezicima kao što su C #, PHP, Ruby, Python, Node itd.

Izrada dokumentacije

Poštarski generator dokumenata odnosi se na zbirku, mapu i opis pojedinačnog zahtjeva te ih uspoređuje tijekom stvaranja ili generiranja dokumentacije za zbirku.

Koristi razne parametre zahtjeva kao što su zaglavlja, parametri niza upita, parametri obrasca i ukazuje na upotrebu tih vrijednosti u dokumentaciji zahtjeva.

Evo video vodiča:

Stvorimo osnovnu zbirku s 3 zahtjeva koristeći isti testni API kao i naši drugi članci. Dodati ćemo neke informacije u opis zbirke, kao i u pojedinačne zahtjeve, a također ćemo stvoriti neke primjere zahtjeva i odgovora, koji će se također zabilježiti tijekom stvaranja dokumentacije.

Slijedite korake u nastavku za dodavanje osnovnih podataka o zahtjevima, a zatim izradu dokumentacije.

# 1) Stvorite zbirku s 3 zahtjeva, tj. Registrirajte korisnika, prijavite korisnika i nabavite korisnika (pogledajte ovdje za korisna opterećenja zahtjeva i API URL-ove).

#dva) Ajmo sada dodati neke informacije u formatu označavanja u zbirku. Oznaka je standardni format koji se koristi za gotovo svu dokumentaciju u Githubu (Za više informacija o umanjenju pogledajte ovdje ).

U opis zbirke u formatu umanjenja označit ćemo dolje neke podatke kao u nastavku.

Opis zbirke u formatu umanjenja vrijednosti

Da biste pregledali kako izgleda umanjenje, pogledajte web portal otvorenog koda ovdje.

Markdown dokumentacija

# 3) Sada ćemo opise dodati pojedinačnim zahtjevima u zbirci. Slično zbirci, format umanjenja je podržan i za opise zahtjeva (Za detaljnije informacije o vodiču za umanjenje pogledajte ovdje ).

Pogledajmo uzorak jednog od zahtjeva za krajnju točku Registriraj korisnika (Isto se može primijeniti i na ostale zahtjeve).

Tekst umanjenja:

API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code

Pregled umanjenja:

Pregled Markdowa

# 4) Za sve API krajnje točke, snimimo ili spremimo primjer koji bi koristio generator dokumentacije.

Primjer nije ništa drugo doli uzorak zahtjeva-odgovora za API zahtjev koji se razmatra. Spremanje odgovora kao primjera omogućuje generatoru dokumentacije da ga uhvati kao dio same dokumentacije.

Da biste spremili primjer, pritisnite 'Poslati' za izvršenje zahtjeva i na kartici odgovora kliknite Spremi odgovor -> Spremi kao primjer .

Spremi primjer

Jednom kada je primjer spremljen, on se nastavlja u zbirci i može mu se pristupiti bilo kada u budućnosti putem Primjeri veza u graditelju zahtjeva.

# 5) Nakon što se dodaju svi gore navedeni podaci, pogledajmo kako stvoriti pregled dokumentacije.

Otvorite opcije sakupljanja i kliknite “ Objavi dokumente '.

Objavi dokumente

Bilješka: Ovdje je važno napomenuti da će samo registrirani korisnici s Poštarom moći koristiti značajku Objavi dokumente na Poštaru. Registracija je besplatna, ali je treba izvršiti putem vašeg računa e-pošte. Postoje i druge mogućnosti / značajke poput dijeljenja zbirki i radnih prostora, stvaranje monitora itd., Koje se dodaju na registrirane račune.

# 6) Jednom “ Objavi dokumente ”Se izvršava, otvara se kartica preglednika s detaljima zbirke poštara (interno poštar hostira ovu kolekciju na vlastite poslužitelje, pored korisničkog lokalnog datotečnog sustava).

Zbirka dokumentacije

Kliknite na 'Pregled' za pregled dokumentacije prije nego što je objavljena.

' Objavi zbirku ”Link će objaviti dokumentaciju na javno dostupnom URL-u. Općenito se ne preporučuje objavljivanje API-ja s osjetljivim informacijama o autorizaciji za objavljivanje na javnom URL-u. Takvi API-ji mogu se objaviti pomoću prilagođenih domena s poslovnim računima poštara.

# 7) Pogledajmo kako izgleda pregled dokumentacije. Klik ' Pregled dokumentacije ”Otvara dokumentaciju u načinu pregleda koji je hostiran na Postmanovim poslužiteljima. Pogledajmo koji su različiti detalji zabilježeni u dokumentaciji (Kao što smo konfigurirali na različitim mjestima. Na primjer , opis zbirke, opis zahtjeva i primjeri).

Uzorak dokumentacije poštara

Opis zahtjeva u Markdown-u

Na gornje 2 snimke zaslona možete vidjeti da su sve informacije dodane u zbirku i opise zahtjeva u pregledu dokumentacije zabilježene na način označen stilom.

popis susjednih ponderiranih grafova c ++

Također, dokumentacija prema zadanim postavkama daje jezične vezove kao što je istaknuto i to olakšava nekome tko želi izravno uputiti API zahtjev na navedenom jeziku.

# 8) Omogućuje vam i izvođenje vrlo osnovnih modifikacija stila, poput promjene boje pozadine, promjene boje pozadine i prednjeg plana predložaka zaglavlja itd. Ali u cjelini, zadani prikaz sam po sebi dovoljan je za objavljivanje stvarno dobrog skupa dokumentacije koja obuhvaća puno važni detalji o API-ju.

Zaključak

U ovom uputstvu prošetali smo kroz podršku za API dokumentaciju koju pruža Postman, pomoću koje uz minimalni napor možemo stvoriti dokumentaciju dobrog izgleda.

Također omogućuje mnoštvo dobrih predložaka i korisnički definirani stil koji se mogu primijeniti na generirane dokumente, a omogućuje i objavljivanje dokumentacije na javnom URL-u.

Za privatne krajnje točke API-ja postoji i odredba o objavljivanju dokumentacije na prilagođenoj domeni koja se može konfigurirati za poslovne račune ili korisnike.

Daljnje čitanje = >> Kako objaviti ugovor o ugovoru za Pact Broker

=> Posjetite ovdje da biste poštara naučili ispočetka.

Preporučena literatura

^