Ako zefektívniť proces tvorby API dokumentácie (nielen) v GoodRequest

Dnes vám prinášame prvý zo série článkov o projektoch z Hackathonu 2021.

V tomto článku by sme Vám radi predstavili prvé z riešení, ktoré vzniklo počas Hackathonu a ako už z názvu tušíte, slúži práve na tvorbu API dokumentácie.

Pri tvorbe API je okrem implementácie samotných endpointov nutné vyhotoviť aj jeho dokumentáciu. Tá bola u nás z historických dôvodov písaná ručne pre každý endpoint pomocou apidocjs. Samozrejme pri každej zmene, ktorá sa počas vývoja vyskytla bolo potrebné upraviť nielen samotný zdrojový kód ale rovnako aj dokumentáciu.

Možno si poviete, že to nie je nič hrozné, len pár minút práce navyše. Ak však spočítame čas potrebný pre vytvorenie dokumentácie pre celý projekt vyšplháme sa pokojne aj na desiatky hodín strávených poctivým prepisovaním. /čas sú peniaze/

V ideálnom svete by výsledkom tejto zdĺhavej práce mala byť správna a aktuálna dokumentácia, ktorou sa môžu riadiť ostatní vývojári.  V tom reálnom však často dochádzalo k chýbam, preklepom alebo aktualizáciám odloženým na neurčito a krvopotne vyťukaná dokumentácia sa stávala neaktuálnou, a teda nepoužiteľnou takmer okamžite.

Tento stav nás trápil už dlhšie no nedarilo sa nám nájsť vhodnejší nástroj, ktorý by nám vyhovoval.  A tak, keď sme sa dozvedeli tému tohtoročného hackathonu, bolo nám úplne jasné na akom projekte budeme pracovať.

Zaujíma vás ako takýto Hackathon zorganizovať? 

Naše ciele

Rozhodli sme sa, že už nebudeme písať nič navyše a vytvoríme knižnicu, ktorá bude schopná vygenerovať API dokumentáciu zo zdrojového kódu. Bolo pre nás dôležité aby bolo riešenie univerzálne použiteľné každým s tech stackom podobným tomu nášmu a aby nevyžadovalo veľký zásah do zdrojového kódu.

A presne to sa nám aj podarilo 🙂

Ako express-joi-to-swagger funguje?

Ešte pred Hackathonom sme začali s prieskumom aby sme si overili, či sú naše odvážne plány vôbec realizovateľné. Na backende používame pre tvorbu API express.js v kombinácií s Joi pre validáciu vstupov a výstupov. Natrafili sme na niekoľko knižníc, ktoré poskytovali čiastkové riešenia a rozhodli sa nimi inšpirovať. Jednou z nich bola knižnica joi-to-swagger, ktorá umožňuje vygenerovať swagger schémy z Joi objektov. Zoznam endpointov zaregistrovaných v express routroch spolu so zoznamom middleware funkcií sme získali vďaka express-list-endpoints. Ostávalo nám teda už len vymyslieť spôsob ako získať Joi schémy a zoznam oprávnení potrebných pre prístup k jednotlivým endpointom tak aby sme nemuseli meniť zdrojový kód. Aj na tento problém sa nám podarilo nájsť riešenie, a tak sme mali na konci prvého dňa hackathonu prototyp, ktorý spĺňal všetky naše kritéria.

Vytvorili sme nástroj, ktorý prešiel zoznamom všetkých endpointov a príslušných middleware-ov a doplnil do swagger dokumentácie nie len samotné cesty(routes) ale aj definície oprávnení a vstupných parametrov.

Náš príbeh nekončí

Asi sa nebudete čudovať, že toto riešenie zožalo veľký úspech. Dokumentácia, ktorá je generovaná automaticky nemôže byť neaktuálna ani nesprávna a okrem toho nám aj šetrí čas.

Po hackathone sa nám podarilo knižnicu doplniť aj o získavanie výstupných schém aby bola dokumentácia naozaj kompletná. Otestovali sme ju na vlastných projektoch, vyladili problémy, ktoré nastali a knižnicu publikovali.  Je dostupná na GitHube alebo npm.  Ako sa píše aj v našom README, budeme radi ak prídete s nápadmi na vylepšenie alebo odhalíte problémy, ktoré sme si nevšimli. Sme otvorení spolupráci s komunitou a každý príspevok do projektu je vítaný 🙂

Sami máme niekoľko plánov. V čase písania článku sa nám podarilo vydať verziu 0.0.15, ktorá umožňuje vyhľadávanie v dokumentácií. Ďalším naším cieľom je do dokumentácie zahrnúť aj automaticky generované summary a možnosť definovať autentifikačné metódy používané pre jednotlivé endpointy alebo celé API.  O našom ďalšom posune Vás budeme určite informovať.

Ani teba nebaví písať dokumentáciu ručne? Pridaj sa k nám do backend tímu!