🥇Pa, RAML ili OAS (Swagger)?

U dinamičnom svijetu mikroservisa može se promijeniti sve — svaka komponenta može biti prepisana na drugom jeziku, koristeći različite okvire i arhitekturu. Neizmjene trebaju ostati samo ugovori kako bi se moglo komunicirati s mikroservisom na nekoj stalnoj osnovi, neovisno o unutarnjim metamorfozama. Danas ćemo govoriti o našem problemu izbora formata za opisivanje ugovora i podijeliti pronađene artefakte.

Objavu je pripremila Anna Melekhova i Vladimir Lapatin

Mikroservisi. Tijekom razvoja Acronis Cyber Cloud shvatili smo da smo ih neizbježno morali koristiti. A projektiranje mikroservisa nemoguće je bez formalizacije ugovora, koji predstavlja sučelje mikroservisa.

Ali kada u proizvodu postoji više od jedne komponente, a razvoj ugovora postaje redovita aktivnost, počinješ razmišljati o optimizaciji procesa. Očigledno je da sučelje (ugovor) i implementacija (mikroservis) moraju odgovarati jedno drugome, da različite komponente trebaju raditi iste stvari na isti način i da, bez centraliziranog donošenja svih tih odluka, svaki tim će ponovno trošiti vrijeme na njihovo postizanje.

Shema mikros servisa Amazon iz tweeta Wernera Vogels, CTO Amazon
U čemu se zapravo sastoji dilema? De facto postoje dva načina interakcije mikroservisa – HTTP Rest i gRPC od Googlea. Ne želeći se uključiti u Googleov tehnološki skup, odabrali smo HTTP Rest. Annotacije za HTTP REST ugovore najčešće se opisuju jednim od dva formata: RAML i OAS, koji je ranije bio poznat kao Swagger. Stoga se svaki tim programera suočava s potrebom da odabere jedan od standarda. No, kako se ispostavilo, donijeti tu odluku može biti jako teško.

Zašto su potrebne anotacije?

Sažetak je potreban kako bi vanjski korisnik mogao lako razumjeti što može raditi s vašom uslugom putem njenog HTTP sučelja. Drugim riječima, na osnovnoj razini sažetak bi trebao sadržavati barem popis dostupnih resursa, njihove HTTP metode, tijela zahtjeva, nabrojavanje parametara, naznačivanje potrebnih i podržanih zaglavlja, kao i kodove povratka i formate odgovora. Ekstremno važan element sažetka ugovora također je i njihovo verbalno opisivanje ("što će se dogoditi ako dodate ovaj query-parametar u zahtjev?", "u kojem će se slučaju vratiti kod 400?")

Ipak, kada se radi o razvoju velikog broja mikroservisa, postoji želja za dodatnom korist od napisanih sažetaka. Na primjer, na temelju RAML/Swaaggera može se generirati i klijentski i serverski kod na velikom broju programskih jezika. Također, može se automatski dobiti dokumentacija za mikroservis i prenijeti je na vašu developer-portalu :).

Primjer strukturiranog opisa ugovora

Rjeđe se susreće praksa testiranja mikroservisa na temelju opisa ugovora. Ako ste napisali i sažetak, i komponentu, možete stvoriti automatski test koji provjerava adekvatnost rada usluge s različitim tipovima podataka na ulazu. Da li usluga vraća kod odgovora koji nije opisan u sažetku? Hoće li ispravno obraditi namjerno netočne podatke?

Štoviše, kvalitetna implementacija ne samo samih ugovora, već i alata za vizualizaciju sažetaka omogućava pojednostavljenje rada s mikroservisom. Drugim riječima, ako je arhitekt kvalitetno opisao ugovor, na temelju toga dizajneri i programeri će integrirati uslugu u druge proizvode bez dodatnih vremenskih troškova.

Za rad dodatnih alata, i RAML i OAS omogućuju dodavanje metapodataka koji nisu predviđeni standardom (na primjer, tako se to radi u OAS).

Uglavnom, polje za kreativnost u primjeni ugovora za mikroservise je ogromno... barem teoretski

Usporedba ježa s užom

Trenutno je prioritetna linija razvoja u Acronisu – razvoj Acronis Cyber Platforme. Acronis Cyber Platforma predstavlja nove točke integracije vanjskih servisa s Acronis Cyber Cloud i agencijskim dijelom. Iako su nas naši interni API-ji, opisani u RAML-u, zadovoljili, potreba za objavom API-ja ponovno je pokrenula pitanje izbora: koji standard anotacija najbolje koristiti za naš rad?

Prvotno se činilo da postoje dva rješenja – najrasprostranjeniji razvojni standardi RAML i Swagger (ili OAS). No, u stvarnosti se pokazalo da alternativa ima barem ne 2, već 3 ili više.

S jedne strane imamo RAML – snažan i učinkovit jezik. Dobro su implementirane hijerarhije i nasljeđivanje, pa je ovaj format više prikladan za velike tvrtke kojima je potrebno mnogo opisa – to jest, ne jedan proizvod, već mnoge mikroservise koji imaju zajedničke dijelove ugovora – sheme autentikacije, jednake tipove podataka, tijela grešaka.

No, razvojnici RAML-a, kompanija Mulesoft, pridružili su se konzorcijumu Open API koji se bavi razvojem Swagger. Stoga je razvoj RAML-a obustavljen. Da zamislite format događaja, zamislite da su glavni održavatelji komponenti sustava Linux otišli raditi u Microsoft. Ova situacija stvara pretpostavke za korištenje Swaggera, koji se dinamički razvija i u posljednjoj – trećoj verziji – praktički sustiže RAML po fleksibilnosti i funkcionalnosti.

Da nije jednog ali…

Kako se ispostavilo, daleko ne koriste sve open-source alate verziju OAS 3.0. Za mikroservise na Go-u najkritičnije će biti odsustvo prilagodbe go-swagger na novu verziju standarda. Razlika između Swagger 2 i Swagger 3 je ogromna.Na primjer, u trećoj verziji, programeri su:

poboljšali opis shema autentikacije,
dovršili podršku za JSON Schema,
povećali mogućnost dodavanja primjera.

Situacija postaje zanimljiva: prilikom odabira standarda treba razmatrati RAML, Swagger 2 i Swagger 3 kao odvojene alternative. U tom slučaju, samo Swagger 2 ima dobru podršku alata OpenSource. RAML je vrlo fleksibilan… i složen, dok Swagger 3 slabo podržavaju zajednice, pa ćete se morati služiti alatima vlastitog razvoja ili komercijalnim rješenjima koja, u pravilu, koštaju prilično skupo.

Pri tome, ako u Swaggeru postoji mnogo korisnih mogućnosti, kao što je gotov portal. editor.swagger.io, na koji možete učitati anotaciju i dobiti njenu vizualizaciju s detaljnim opisom, vezama i odnosima, ali za temeljitiji i manje prijateljski RAML takva mogućnost ne postoji. Da, možete potražiti nešto među projektima na GitHubu, pronaći ekvivalent i sami ga postaviti. Međutim, u svakom slučaju, netko će morati održavati portal, što nije tako zgodno za osnovnu upotrebu ili testne potrebe. Osim toga, Swagger je više "bezprincipijelan", ili liberalan — može se generirati iz komentara u kodu, što naravno ide protiv načela API first i nije podržano ni jednim alatom RAML.

U svoje vrijeme smo počeli raditi s RAML-om, kao fleksibilnijim jezikom, i na kraju smo morali mnogo toga raditi ručno. Na primjer, u jednom od projekata koristi se alat ramlfications u unit testovima, koji podržava samo RAML 0.8. Tako da smo morali dodavati improvizacije, kako bi alat mogao "konzumirati" RAML verzije 1.0.

Je li potrebno birati?

Nakon isprobavanja rješenja ekosustava za RAML, došli smo do zaključka da moramo konvertirati RAML u Swagger 2 i već u njemu provoditi svu automatizaciju, verifikaciju, testiranje i kasniju optimizaciju. To je dobar način da se istovremeno iskoristi fleksibilnost RAML-a i podrška alata zajednice od Swaggera.

Za rješavanje ovog zadatka postoje dva OpenSource alata koja bi trebala osigurati konverziju ugovora:

oas-raml-converter – trenutno nepodržavani alat. Tijekom rada s njim otkrili smo da ima niz problema s kompleksnim RAML-ima koji su "raspršeni" po velikom broju datoteka. Ovaj program je napisan u JavaScriptu i izvršava rekurzivnu obrada sintaktičkog stabla. Zbog dinamičkog tipiziranja, snalaziti se u ovom kodu postaje vrlo teško, pa smo odlučili ne trošiti vrijeme na pisanje zakrpa za umirući alat.
webapi-parser — alat iste tvrtke koji tvrdi da je spreman konvertirati sve i svašta, u svim smjerovima. Do danas, podržava RAML 0.8, RAML 1.0 i Swagger 2.0. Međutim, u vrijeme našeg istraživanja, alat je još uvijek bio IZUZETNO nespretan i neprikladan za korištenje. Razvijači stvaraju svojevrsni IR, što će im omogućiti brzo dodavanje novih standarda u budućnosti. No, trenutno to jednostavno ne funkcionira.

I to nije sve poteškoće s kojima smo se suočili. Jedan od koraka našeg pipelinea je provjeriti da li je RAML iz repozitorija ispravan u odnosu na specifikaciju. Isprobali smo nekoliko alata. Uzimajući u obzir, svi su se bunili zbog naših oznaka na različitim mjestima koristeći različite glupe riječi. I to ne uvijek s razlogom :).

Na kraju smo se odlučili za sada već zastarjeli projekt, koji također ima niz problema (ponekad se ruši bez razloga, ima problema s radom s regularnim izrazima). Tako da nismo pronašli način za rješavanje problema validacije i konverzije pomoću besplatnih alata, pa smo se odlučili koristiti komercijalni alat. U budućnosti, kada OpenSource alati postanu razvijeniji, rješavanje ovog problema će možda postati lakše. A za sada su troškovi rada i vremena na 'dorađivanje' djelovali veći od cijene komercijalne usluge.

Zaključak

Nakon svega ovoga poželjeli smo podijeliti iskustvo i istaknuti da prilikom odabira alata za opisivanje ugovora trebate jasno odrediti što želite i koji budžet ste spremni uložiti. Ako zaboravite na OpenSource, već sada postoji puno usluga i proizvoda koji pomažu u provjeri, konverziji i validaciji. No, oni su skupi, a ponekad čak i vrlo skupi. Za veliku kompaniju takvi troškovi su podnošljivi, ali za startup mogu predstavljati veliki teret.

Odredite skup alata koje ćete koristiti kasnije. Na primjer, ako trebate samo prikazati ugovor, lakše će biti koristiti Swagger 2, koji ima lijep API, jer ćete u RAML-u morati sami podignuti i održavati servis.
Što više zadataka imate, veća će biti potreba za alatima, a oni su različiti za različite platforme, pa je bolje odmah se upoznati s dostupnim verzijama kako biste donijeli odluku koja će minimizirati vaše troškove u budućnosti.

No, trebamo priznati da su sve ekosustave koje danas postoje nesavršene. Stoga, ako u kompaniji postoje zaljubljenici koji vole raditi u RAML-u jer "omogućuje fleksibilnije izražavanje misli", ili, s druge strane, preferiraju Swagger jer "je jasniji", najbolje je dopustiti im da rade u onome čemu su navikli i što žele, jer alati bilo kojeg od formata zahtijevaju doradu.

Što se tiče našeg iskustva, u sljedećim postovima ćemo govoriti o tome koje statičke i dinamičke provjere provodimo na temelju naše RAML-Swagger arhitekture, kao i o dokumentaciji koju generiramo iz ugovora i na koji način sve to funkcionira.

Samo registrirani korisnici mogu sudjelovati u anketi. Prijavite se, molimo.