🥇Takže RAML alebo OAS (Swagger)?

Vo dynamickom svete mikroservisov sa môže zmeniť čokoľvek — akúkoľvek zložku je možné prepísať v inom jazyku pomocou rôznych rámcov a architektúr. Nemenné musia zostať iba zmluvy, aby bolo možné s mikroservisom interagovať zvonka na nejakej stabilnej báze, bez ohľadu na vnútorné metamorfózy. A dnes sa s vami podelíme o našu problematiku voľby formátu popisu zmlúv a zdieľame nájdené artefakty.

Príspevok pripravil Anna Melechova a Vladimir Lapatin

Mikroservisy. Pri vývoji Acronis Cyber Cloud sme si uvedomili, že sa im nedokážeme vyhnúť. Návrh mikroservisu nie je možný bez formalizácie zmluvy, ktorá predstavuje rozhranie mikroservisu.

Ale keď produkt obsahuje viac než jednu zložku a vývoj zmluvy sa stáva pravidelnou aktivitou, nevyhnutne začnete uvažovať o optimalizácii procesu. Stáva sa očividným, že rozhranie (zmluva) a implementácia (mikroservis) si musia navzájom zodpovedať, že rôzne zložky by mali robiť rovnaké veci rovnakým spôsobom, a že bez centralizovaného prijímania všetkých týchto rozhodnutí bude každé tím nútený znova a znova strácať čas ich získavaním.

Schéma mikroservisov Amazon z tweety Wernera Vogelesa, CTO Amazon
V čom spočíva dilema? De facto existujú dva spôsoby interakcie mikroservisov – HTTP Rest a gRPC od spoločnosti Google. Aby sme sa nechceli zapájať do technologického zásobníka Google, zvolili sme HTTP Rest. Anotácie k zmluvám HTTP REST sa najčastejšie opisujú jedným z dvoch formátov: RAML a OAS, predtým známy ako Swagger. Preto sa každé vývojárske tím stretáva s potrebou urobiť voľbu v prospech jedného z štandardov. Ale ako sa ukázalo, urobiť túto voľbu môže byť veľmi zložité.

Na čo sú anotácie potrebné?

Anotácia je potrebná na to, aby externý používateľ mohol ľahko pochopiť, čo môže robiť s vašou službou cez jej HTTP rozhranie. To znamená, že na základnej úrovni by mala anotácia obsahovať minimálne zoznam dostupných zdrojov, ich HTTP metód, telá dopytov, vymenovanie parametrov, uvedenie nevyhnutných a podporovaných hlavičiek, ako aj kódov návratu a formátov odpovedí. Mimoriadne dôležitým prvkom anotácie zmluvy je aj ich slovný opis („čo sa stane, ak pridáte tento query parameter k dopytu?“, „v akých prípadoch sa vráti kód 400?“)

Napriek tomu, keď ide o vývoj veľkého množstva mikroslužieb, je možné získať ďalšie výhody z napísaných anotácií. Napríklad, na základe RAML/Swagger je možné generovať klientsky aj serverový kód na obrovskom množstve programovacích jazykov. Okrem toho je možné automaticky získavať dokumentáciu k mikroslužbe a nahrávať ju na váš developer-portal : ).

Príklad štruktúrovaného opisu zmluvy

Zriedkavejšie sa stretáva prax testovania mikroslužieb na základe opisov zmlúv. Ak ste napísali ako anotáciu, tak aj komponent, môžete vytvoriť autotest, ktorý overí primeranosť fungovania služby s rôznymi typmi dát na vstupe. Nevracia služba kód odpovede, ktorý nie je opísaný v anotácii? Dokáže správne spracovať zjavne nesprávne dáta?

Navyše, kvalitná implementácia nie len samotných zmlúv, ale aj nástrojov na vizualizáciu anotácií umožňuje zjednodušiť prácu s mikroslužbou. Tým pádom, ak architekt kvalitne opísal zmluvu, na jej základe dizajnéri a vývojári budú implementovať službu do iných produktov bez dodatočných časových nákladov.

Na prácu s dodatočnými nástrojmi RAML aj OAS majú možnosť pridať metadáta, ktoré nie sú predpísané štandardom (napríklad, takto sa to robí v OAS).

Celkovo je pole pre kreativitu v aplikácii zmlúv pre mikroslužby obrovské... aspoň teoreticky

Porovnanie ježka s hadom

V súčasnosti je prioritným smerom vývoja v Acronis rozvoj Acronis Cyber Platform. Acronis Cyber Platform sú nové body integrácie externých služieb s Acronis Cyber Cloud a agendovou časťou. Hoci naše interné API, opísané v RAML, nám vyhovovali, potreba publikovania API opäť vyvolala otázku výberu: ktorý štandard anotácií je pre našu prácu najlepší?

Najprv sa zdalo, že existujú dve riešenia — najrozšírenejšie vývojové rámce RAML a Swagger (alebo OAS). Ale v skutočnosti sa ukázalo, že alternatív je aspoň nie 2, ale 3 alebo viac.

Na jednej strane je tu RAML – mocný a efektívny jazyk. V ňom je dobre implementovaná hierarchia a dedenie, takže tento formát je vhodnejší pre veľké spoločnosti, ktoré potrebujú množstvo popisov — teda nie jeden produkt, ale mnoho mikroslužieb, ktoré majú spoločné časti kontraktov — schémy autentifikácie, rovnaké typy dát, telá chýb.

Ale vývojár RAML, spoločnosť Mulesoft, sa pripojil k konzorciu Open API, ktoré sa zaoberá rozvojom Swagger. Preto sa vývoj RAML pozastavil. Aby ste si predstavili formát udalosti, predstavte si, že správcovia hlavných komponentov Linuxu odišli pracovať do Microsoftu. Taká situácia vytvára predpoklady na použitie Swagger, ktorý sa dynamicky vyvíja a v poslednej — tretej verzii — takmer dobehne RAML z pohľadu flexibility a funkčnosti.

Keby nebolo jedného "ale"...

Ako sa ukázalo, ďaleko nie všetky open-source nástroje sa aktualizovali na verziu OAS 3.0. Pre mikroslužby na Go bude najkritickejším chýbajúca adaptácia go-swagger na čerstvú verziu štandardu. Rozdiel medzi Swagger 2 a Swagger 3 je obrovský. Napríklad v tretej verzii vývojári:

vylepšili popis schém autentifikácie
dopracovali podporu JSON Schema
zvýšili možnosť pridávania príkladov

Situácia je zábavná: pri výbere štandardu je potrebné považovať RAML, Swagger 2 a Swagger 3 za samostatné alternatívy. Pri tom má len Swagger 2 dobrú podporu nástrojov OpenSource. RAML je veľmi flexibilný… a zložitý, zatiaľ čo Swagger 3 je slabšie podporovaný komunitou, takže budete musieť používať nástroje vlastného vývoja alebo komerčné riešenia, ktoré zvyčajne stoja dosť veľa.

Pri tom ak existuje mnoho príjemných možností v Swagger, ako je hotový portál editor.swagger.io, na ktorý môžete nahrať anotáciu a získať jej vizualizáciu s podrobným popisom, odkazmi a vzťahmi, avšak pre RAML, ktorý je základnejší a menej priateľský, nie je takáto možnosť k dispozícii. Áno, môžete sa pokúsiť niečo nájsť medzi projektmi na GitHub, nájsť tam podobný nástroj a samostatne ho rozbehnúť. Napriek tomu by sa niekto mal postarať o portál, čo nie je veľmi pohodlné na základné používanie alebo testovacie potreby. Okrem toho, swagger je viac 'bez zásad', alebo liberálny - môže sa generovať z komentárov v kóde, čo samozrejme ide proti princípu API first a nijaká z RAML utilít to nepodporuje.

V minulosti sme začali pracovať s RAML, ako s flexibilnejším jazykom, a nakoniec sme museli veľa robiť sami. Napríklad, v jednom z projektov používame nástroj ramlfications v jednotkových testoch, ktorý podporuje len RAML 0.8. Takže sme museli pridať obmedzenia, aby nástroj mohol 'jesť' RAML verzie 1.0.

A je potrebné vyberať?

Po množstve dodatočného písania ekosystému riešení pre RAML sme dospeli k záveru, že potrebujeme konvertovať RAML na Swagger 2 a už v ňom vykonávať všetku automatizáciu, kontrolu, testovanie a následnú optimalizáciu. Toto je dobrý spôsob, ako využiť flexibilitu RAML a podporu tento nástroj od komunity Swagger.

Na tento problém existujú dva OpenSource nástroje, ktoré by mali zabezpečiť konverziu kontraktov:

oas-raml-converter – v súčasnosti nepodporovaná utilita. Počas práce s ňou sme zistili, že má množstvo problémov so zložitými RAML, ktoré sú 'rozptýlené' v mnohých súboroch. Tento program je napísaný v JavaScripte a vykonáva rekurzívne prechádzanie syntaktického stromu. Kvôli dynamickému typizovaniu sa v tomto kóde ťažko orientuje, takže sme sa rozhodli nestrácať čas písaním záplat pre umierajúcu utilitu.
webapi-parser — nástroj od tej istej spoločnosti, ktorá sa snaží konvertovať všetko a všade, a to v akomkoľvek smere. K dnešnému dňu je deklarovaná podpora RAML 0.8, RAML 1.0 a Swagger 2.0. Avšak v čase našich výskumov bola utilita ešte OVER nezrelá a nepoužiteľná. Vývojári vytvárajú akýsi IR, čo im v budúcnosti umožní rýchlo pridávať nové štandardy. Ale zatiaľ to jednoducho nefunguje.

A to nie sú všetky komplikácie, ktorým čelíme. Jedným zo krokov nášho pipeline je overenie toho, že RAML z repozitára je správne vzhľadom na špecifikáciu. Vyskúšali sme niekoľko nástrojov. Prekvapujúce je, že všetky sa sťažovali na naše anotácie na rôznych miestach a úplne rôznymi nevhodnými slovami. A nie vždy to bolo na mieste :).

Nakoniec sme sa rozhodli pre dnes už zastaraný projekt, ktorý má tiež množstvo problémov (niekedy sa zrúti bez zjavného dôvodu, má problémy pri práci s regulárnymi výrazmi). Takže sme nenašli spôsob, ako vyriešiť úlohy validácie a konverzie na základe bezplatných nástrojov, a rozhodli sme sa využiť komerčný nástroj. V budúcnosti, keď sa OpenSource nástroje stanú vyvinutejšími, bude možno riešenie tejto úlohy jednoduchšie. A zatiaľ sa nám náklady na „dodatočné doladenie“ zdali byť väčšie, ako náklady na komerčnú službu.

Záver

Po všetkom tom sme mali chuť podeliť sa o skúsenosti a poznamenať, že pred výberom nástroja na popis zmlúv je potrebné presne definovať, čo od neho očakávate, a aký rozpočet ste ochotní investovať. Ak zabudneme na OpenSource, už teraz existuje množstvo služieb a produktov, ktoré vám pomôžu s overením, konverziou a validáciou. Ale sú drahé, a niekedy veľmi drahé. Pre veľkú spoločnosť sú tieto náklady prijateľné, ale pre startupy môžu predstavovať veľké zaťaženie.

Definujte súbor nástrojov, ktoré budete neskôr používať. Napríklad, ak potrebujete iba zobraziť zmluvu, bude jednoduchšie použiť Swagger 2, ktorý má pekné API, lebo v RAML budete musieť prevádzkovať a udržiavať službu sami.
Čím viac úloh budete mať, tým širšia bude potreba nástrojov, a tie sú rôzne pre rôzne platformy, a je lepšie sa hneď oboznámiť s dostupnými verziami, aby ste mali na výber, ktorý minimalizuje vaše budúce náklady.

Je dôležité uznať, že všetky ekosystémy, ktoré dnes existujú, sú nedokonalé. Preto, ak má spoločnosť fanúšikov, ktorí uprednostňujú prácu v RAML, pretože "umožňuje flexibilnejšie vyjadriť myšlienky", alebo naopak, tých, ktorí preferujú Swagger, pretože "je prehľadnejší", je najlepšie nechať ich pracovať s tým, na čo sú zvyknutí a čo chcú, pretože nástroje oboch formátov vyžadujú doladenie.

Pokiaľ ide o naše skúsenosti, v nasledujúcich príspevkoch sa podelíme o to, aké statické a dynamické kontroly vykonávame na našej RAML-Swagger architektúre, ako aj o tom, akú dokumentáciu generujeme z kontraktov a ako to všetko funguje.

Len registrovaní používatelia sa môžu zúčastniť prieskumu. Prihláste sa, prosím.