Meni

Kako ustvariti dokumentacijo API v poštarju?

  • Glavni
  • Drugo
  • Kako ustvariti dokumentacijo API v poštarju?

how create api documentation postman

Preizkusite Naš Instrument Za Odpravo Težav

Ta vadnica razlaga, kako z minimalnimi napori ustvariti lepo videti, oblikovano dokumentacijo z uporabo API-jeve podpore za dokumentacijo, ki jo nudi orodje Postman:

Dokumentacija za kateri koli API, bodisi notranji bodisi javni, je ena najpomembnejših sestavin za njegov uspeh.

Glavni razlog za to je, da je dokumentacija način komunikacije z uporabniki.

  • Kako naj se uporablja vaš API?
  • Katere kode stanja so podprte?
  • Katere so kode napak?
  • Katere vrste metod so izpostavljene?

Vse te informacije so potrebne za uporabo ali izvajanje API-ja za želene potrebe.

=> Tukaj bodite pozorni na preprosto serijo usposabljanj za poštarje.

Poštar - Ustvarjanje dokumentacije API

top 5 vohunskih aplikacij za android

Postman ponuja metodologijo dokumentacije, ki je enostavna za uporabo, za osnovno dokumentacijo pa je preprosto, kot če kliknete gumb v zbirki Postman, in dobite javni URL za dokumentacijo API.

Kaj se boste naučili:

Ustvarjanje dokumentacije API v poštarju

Značilnosti dokumentacije

Izstopajoče lastnosti generatorja dokumentacije Postman vključujejo:

  • Podpira sintakso označevanja. Markdown je splošna sintaksa dokumentacije, ki bi jo običajno opazili pri katerem koli projektu Github. Omogoča lažje oblikovanje in oblikovanje besedila.
  • Ni posebnih sintaks / zahtev za ustvarjanje dokumentacije. Informacije o zahtevah in zbirkah se na najboljši način uporabljajo za ustvarjanje dokumentacije.
  • Lahko se objavi na javnem URL-ju ali v domeni po meri (za poslovne uporabnike).
  • Ustvari delčke kode za klicanje API-ja v različnih jezikih, kot so C #, PHP, Ruby, Python, Node itd.

Ustvarjanje dokumentacije

Generator dokumentov Postman se sklicuje na zbirko, mapo in opis posamezne zahteve ter jih med ustvarjanjem ali ustvarjanjem dokumentacije za zbirko primerja.

Uporablja različne parametre zahteve, kot so glave, parametri niza poizvedbe, parametri obrazca in označuje uporabo teh vrednosti v dokumentaciji zahteve.

Tu je video vadnica:

Ustvarimo osnovno zbirko s tremi zahtevami z uporabo istega testnega API-ja kot naši drugi članki. Dodali bomo nekaj informacij tako opisu zbirke kot posameznim zahtevam in ustvarili tudi nekaj primerov zahtev in odgovorov, ki bodo prav tako zajeti med ustvarjanjem dokumentacije.

Sledite spodnjim korakom za dodajanje osnovnih informacij o zahtevah in nato ustvarjanje dokumentacije.

# 1) Ustvari zbirko s 3 zahtevami, tj. Registriraj uporabnika, prijavi uporabnika in pridobi uporabnika (glej tukaj za koristne obremenitve zahtev in URL-je API-jev).

#two) Zdaj v zbirko dodajte nekaj informacij v obliki znižanja. Markdown je standardna oblika, ki se uporablja za skoraj vso dokumentacijo v Githubu (za več informacij o označevanju glejte tukaj ).

Opisu zbirke bomo dodali nekaj informacij v obliki zmanjšanja vrednosti, kot je prikazano spodaj.

Opis zbirke v obliki zmanjšanja vrednosti

Če si želite ogledati predogled znižanja, si oglejte odprtokodni spletni portal tukaj.

Markdown dokumentacija

# 3) Zdaj bomo opise dodali posameznim zahtevam v zbirki. Podobno kot zbirka je tudi oblika opisov podprta za opise zahtev (za podrobnejše informacije o vodniku za zmanjšanje glejte tukaj ).

Oglejmo si vzorec ene od zahtev za končno točko Registriraj uporabnika (enako lahko uporabimo tudi za druge zahteve).

Besedilo označevanja:

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

Predogled Markdown:

Predogled Markdown

# 4) Za vse končne točke API zajemimo ali shranimo primer, ki bi ga uporabil generator dokumentacije.

Primer ni nič drugega kot vzorec zahteve-odgovora za obravnavano zahtevo API. Shranjevanje odziva kot primer omogoča, da ga generator dokumentacije zajame kot del same dokumentacije.

Če želite shraniti primer, pritisnite »Pošlji« za izvedbo zahteve in na zavihku za odgovor kliknite Shrani odgovor -> Shrani kot primer .

Shrani primer

Ko je primer shranjen, se ohrani v zbirki in do njega lahko kadar koli v prihodnosti dostopate prek Primeri povezava v graditelju zahtev.

# 5) Ko so dodane vse zgornje informacije, poglejmo, kako ustvariti predogled dokumentacije.

Odprite možnosti zbiranja in kliknite » Objavi Dokumente '.

Objavi Dokumente

Opomba: Pomembno je omeniti, da bodo lahko samo registrirani uporabniki z Postmanom uporabljali funkcijo Publish docs v programu Postman. Registracija je brezplačna, vendar jo je treba opraviti prek vašega e-poštnega računa. Obstajajo tudi druge zmogljivosti / funkcije, kot so skupna raba zbirk in delovnih prostorov, ustvarjanje monitorjev itd., Ki se dodajo registriranim računom.

# 6) Ko Objavi Dokumente 'Se odpre, odpre se zavihek brskalnika s podrobnostmi o zbirki poštarjev (interno poštar to zbirko gosti tudi na lastnih strežnikih poleg uporabnikovega lokalnega datotečnega sistema).

Zbirka dokumentacije

Kliknite na 'Predogled' za ogled dokumentacije, preden je objavljena.

' Objavi zbirko 'Povezava bo objavila dokumentacijo na javno dostopen URL. Običajno ni priporočljivo objavljati API-jev z občutljivimi informacijami o pooblastilu za objavo na javnem URL-ju. Takšne API-je je mogoče objaviti z uporabo domen po meri z računi podjetja Postman.

# 7) Poglejmo, kako izgleda predogled dokumentacije. S klikom na Predogled dokumentacije «Odpre dokumentacijo v načinu predogleda, ki gostuje na Postmanovih strežnikih. Poglejmo, katere različne podrobnosti so zajete v dokumentaciji (Kot smo konfigurirali na različnih mestih. Na primer , opis zbirke, opis zahteve in primeri).

Vzorec dokumentacije poštarja

Opis zahteve v Markdown

Na zgornjih dveh posnetkih zaslona lahko vidite, da so vse informacije, ki so bile dodane zbirki in opisom zahtev, v predogledu dokumentacije zajete na način, označen z oznako.

kako drugačen je c ++ od jave

Tudi privzeto dokumentacija vsebuje jezikovne vezi, kot so označene, kar olajša tiste, ki želijo neposredno zahtevati API v navedenem jeziku.

# 8) Omogoča tudi izvedbo zelo osnovnih modifikacij, kot so spreminjanje barve ozadja, spreminjanje barve ozadja in ospredja v predlogah glave itd. Toda na splošno že sam privzeti pogled zadošča za objavo res dobrega sklopa dokumentacije, ki zajema veliko pomembne podrobnosti o API-ju.

Zaključek

V tej vadnici smo se sprehodili po podpori za dokumentacijo API-ja, ki jo je zagotovil Postman, s pomočjo katere lahko z minimalnim naporom ustvarimo lepo oblikovano dokumentacijo.

Omogoča tudi veliko dobrih predlog in uporabniško določen slog, ki bi ga bilo mogoče uporabiti za ustvarjene dokumente, ter omogoča objavljanje dokumentacije tudi na javnem URL-ju.

Za zasebne končne točke API obstaja tudi določba za objavo dokumentacije v domeni po meri, ki jo je mogoče konfigurirati za poslovne račune ali uporabnike.

Nadaljnje branje = >> Kako objaviti Pact Contract to Pact Broker

=> Obiščite tukaj, če želite izvedeti poštarja iz nič.

Priporočeno branje

^