Poznáte to. Robíte vývoj, potrebujete nejakú knižnicu, otvoríte npmjs.com a začnete hľadať. Milióny knižníc. Každá robí niečo, niektorá viac, niektorá menej, niektorá lepšie, niektorá horšie. Každá však plní disk v adresári node_modules 😬.

Čo však robiť, keď nenájdete to, čo hľadáte? Naprogramujete si vlastnú, predsa!

Ale poporiadku. Neviem, či viete, ale API servre programujeme v node.js. Čo ani nie je nič nezvyčajné, to dnes zvláda nadpriemerný študent strednej školy. Podstata našej práce spočíva v návrhu servra, návrhu vstupov a výstupov, v biznis logike. A dokumentácii. Kto rád píše dokumentáciu? Snáď nikto. Ale každý, či už programátor, alebo technicky zdatný zákazník ju rád číta a kritizuje.

A tak sme sa rozhodli pred pár rokmi vyvíjať spôsobom, aby dokumentácia bola základ. Veľmi príjemné spojenie sme našli v špecifikácii OpenAPI Specification V3 (OAS3).

Čo nám to prináša?

  • popis API, definíciu schém parametrov na vstupe a na výstupe
  • automaticky generovanú dokumentáciu, ktorá zároveň slúži aj ako test requestov
  • a v závislosti od použitého frameworku automatický router a validátor vstupov

A práve posledný bod je v node.js problém. Ako základ http servra používame knižnicu koa.js. Má skoro dvojnásobný výkon oproti express. Má príjemnú schému middlewarov. Využíva generátory a asynchrónny kód. Ľahko sa implementuje a nenabaľuje zbytočný balast nad native http(s) modul.

Lenže knižnicu, ktorá by zobrala na jednej strane OpenAPI špecifikáciu, na strane druhej Koa aplikáciu a spojila by to so všetkými výhodami, sme hľadali len márne. A tak sme si malú – 500 riadkovú knižnicu spravili sami. Je to kompilát viacerých knižníc, z ktorých každá plní svoju funkciu a robí ju dobre.

Koa + OAS3 = KOAS3

Samostatnou knižnicou sme zabili viacero múch jednou ranou:

  1. Knižnica vytvorí router, ktorý nasadíte do existujúcej Koa aplikácie ako middleware. Takto ho viete začleniť pomedzi ďalšie, už existujúce routre a middlewares, alebo spraviť len časť aplikácie pomocou OpenAPI. Hodí sa to vtedy, keď riešite problém, ktorý OAS3 nepodporuje, alebo napríklad potrebujete na nejakú URL zavesiť stream, alebo Websocket server.
  2. Z OpenAPI sa zoberie definícia security (autentifikácie a autorizácie) a automaticky je každý request chránený tak, ako bol vyšpecifikovaný v OAS3. Jednotlivé security handlery si samozrejme musíte napísať sami 🙂
  3. Každý parameter requestu je skontrolovaný a zvalidovaný voči špecifikácii. Nemusíte sa teda v controlleri starať o to, či vám ID používateľa prišlo ako integer, alebo string. Ak ste ho špecifikovali ako integer, na 100% je integer, inak KOAS3 vráti chybový http response 400 Bad Request.
  4. Ako bonus, KOAS3 vytvorí routu, na ktorú zavesí úhľadnú dokumentáciu, obvykle je to na /docs – napríklad špecifikácia k našej aplikácii Pages.

Ako sa to implementuje? Všetko potrebné nájdete na stránke balíka npm koas3.

Momentálne máme na KOAS3 už skoro polovicu API služieb v projekte SportNet. Za ten čas sme našli fičúri, ktoré chýbajú a potrebujeme ich doplniť. Malý roadmap:

  • Urobiť podporu pre viac OpenAPI súborov, navzájom závislých
  • Urobiť podporu pre externé referencie v OpenAPI špecifikácii
  • Doplniť vlastné formáty validátorov na parametre, napríklad by sme chceli pridať k už existujúcim date-time, či email aj url a ObjectId.
  • No a samozrejme nad knižnicou doplniť automatizované testy s code coverage 100% 🤞

KOAS3 je momentálne vo verzii 0.0.5. Čaká nás dlhá cesta k verzii 1.0.0. Vyskúšajte a pomôžte nám s tým. Opensource projekt je len tak dobrý, akých dobrých má contributorov.

 

Neprehliadnite výsledky našej programátorskej práce.