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:
- 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.
- 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 :-)
- 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.
- 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.
