API yra tokia gera, kokia yra jos dokumentacija, todėl įsitikinkite, kad jūsiškis yra lengvai suprantamas ir naudojamas naudojant „Postman“ palaikymą.
Dokumentacija yra esminis API kūrimo ciklo aspektas. Tai padeda vartotojams suprasti jūsų API funkcionalumą ir tai, kaip jie gali su ja sąveikauti. Dokumentacijoje turėtų būti paaiškinta, kaip pateikti užklausas API, parametrus, kuriuos palaiko kiekvienas galutinis taškas, ir atsakymų, kurių galite tikėtis.
Šiuolaikiniai API įrankiai supaprastina dokumentų kūrimo, testavimo ir dalijimosi procesą, o vienas iš šių įrankių yra „Postman“.
„Postman“ yra populiarus kelių platformų API kūrimo ir testavimo įrankis. Tai suteikia jums paprastą ir efektyvų būdą kurti, išbandyti ir bendrinti API bei jų dokumentaciją.
Kodėl turėtumėte naudoti „Postman“ savo API dokumentacijai
Paštininkas suteikia naudotojo patirtį bandant API ir kuriant interaktyvią dokumentaciją. Tai leidžia išbandyti API tiesiai iš jos dokumentų. Ši funkcija naudinga atliekant daugelį operacijų, įskaitant tikrinimą, ar API veikia ir veikia taip, kaip numatyta.
Štai šešios priežastys, kodėl turėtumėte apsvarstyti galimybę naudoti „Postman“ API dokumentacijos projektui:
- Patogi vartotojo sąsaja: „Postman“ vartotojo sąsaja suteikia švarią, intuityvią ir gerai organizuotą darbo vietą, skirtą kurti, išbandyti ir dokumentuoti API. Galite kurti naujas užklausas, pridėti parametrų, antraščių ir autentifikavimo bei išbandyti juos iš vienos vietos neperjungdami įrankiai.
- API testavimas: galite siųsti užklausas savo API, peržiūrėti atsakymą ir įsitikinti, kad viskas veikia taip, kaip tikėtasi. Tai leidžia anksti nustatyti ir išspręsti visas problemas, sumažinant netikėtų klaidų riziką.
- Bendradarbiavimas: Postman turi galingų bendradarbiavimo funkcijų, kurias galite naudoti norėdami bendrinti savo API su suinteresuotosiomis šalimis ir bendradarbiauti kuriant. Galite kurti kolekcijas, pakviesti komandos narius jas peržiūrėti ir redaguoti bei palikti visus tame pačiame puslapyje.
- Automatizuotas testavimas: „Postman“ įtaisytas bandymų vykdytojas leidžia rašyti automatinius API testus. Galite nustatyti testus, kurie bus vykdomi kiekvieną kartą, kai keičiate API, kad įsitikintumėte, jog viskas veikia ir dokumentacija yra tinkama data.
- Dokumentacijos generavimas: „Postman“ gali sutaupyti jūsų laiko ir pastangų automatiškai generuodamas API dokumentaciją. Galite tinkinti dokumentaciją pagal savo prekės ženklą ir stilių ir bendrinti jas su kitais HTML, PDF ir Markdown formatas.
- Integracijos: „Postman“ integruojasi su kitais įrankiais, kuriuos galbūt naudojate, pvz., nuolatinio integravimo ir diegimo (CI / CD) įrankiais, problemų stebėjimo priemonėmis ir kt. Taip lengviau išlaikyti nuoseklias ir supaprastintas darbo eigas, sumažinant klaidų riziką ir padidinant efektyvumą.
Kaip dirbti su paštininku
Pirmiausia turėsite sukurti kolekciją, kad sugrupuotumėte API užklausas. Galite sukurti kolekciją skirtuke Kolekcijos; būtinai pavadinkite savo kolekciją.
Sukūrę rinkinį, galite pridėti API užklausas ir išbandyti galinius taškus, kad įsitikintumėte, jog jie veikia taip, kaip numatyta.
Naudoti Sutaupyti mygtuką, esantį užklausos skirtuko viršuje, kad išsaugotumėte kiekvieną sukonfigūruotą užklausą savo kolekcijoje.
Pridėję ir išsaugoję užklausas prie kolekcijos, galite pereiti prie dokumentacijos etapo.
API dokumentavimas
„Postman“ teikia redagavimo įrankį jūsų API dokumentavimui. Pasirinkę kolekciją viršutiniame dešiniajame „Postman“ programos kampe, spustelėkite dokumento mygtuką, kad pasiektumėte dokumentacijos įrankį.
Atidarę dokumentacijos įrankį, galite pradėti rašyti dokumentus. Redagavimo priemonė palaiko Markdown sintaksę ir pateikia neapdoroto teksto redagavimo įrankius.
Štai GET užklausos galutinio taško dokumentacijos pavyzdys:
Galite dokumentuoti savo API pagal specifikacijas, pvz., OpenAPI pagerinti API dokumentacijos kokybę ir skaitomumą.
Baigę dokumentuoti API, galite paskelbti dokumentus naudodami Paskelbti mygtuką dokumentacijos rodinio viršuje, dešinėje.
Paštininkas atidarys tinklalapį, kuriame galite tinkinti API dokumentaciją ir jos stilių.
Baigę sukonfigūruoti ir suformuluoti dokumentaciją, galite pradėti ją skelbti. Postman sukurs tinklalapį, kuriame jūsų vartotojai galės pasiekti dokumentaciją ir išbandyti jūsų API funkcionalumą.
Spustelėkite parinkčių mygtuką (...) kolekcijų skirtuke, kad sukurtumėte dokumentus kitais formatais.
Šios mokymo programos dokumentacijos pavyzdį galite rasti adresu šis paštininko dokumentacijos tinklalapis.
Galite išbandyti savo API naudodami „Postman“.
Postman yra universalus, suprantamas įrankis, galintis palengvinti API dokumentacijos procesą. Taip pat galite išbandyti įvairių tipų API, nuo REST iki SOAP, GraphQL ir OAuth.
Postman taip pat palaiko platų API stilių spektrą, įskaitant gRPC ir WebSockets. Dėl visų šių savybių „Postman“ yra puikus įrankis jūsų kūrimo arsenale.
