{"id":38022,"date":"2019-10-31T22:21:14","date_gmt":"2019-10-31T19:21:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/tak-vse-taki-raml-ili-oas-swagger\/"},"modified":"2019-10-31T22:21:14","modified_gmt":"2019-10-31T19:21:14","slug":"tak-vse-taki-raml-ili-oas-swagger","status":"publish","type":"post","link":"https:\/\/prohoster.info\/sk\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Tak predsa RAML alebo OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Vo dynamickom svete mikroservisov sa m\u00f4\u017ee zmeni\u0165 \u010doko\u013evek \u2014 ak\u00fako\u013evek zlo\u017eku je mo\u017en\u00e9 prep\u00edsa\u0165 v inom jazyku pomocou r\u00f4znych r\u00e1mcov a architekt\u00far. Nemenn\u00e9 musia zosta\u0165 iba zmluvy, aby bolo mo\u017en\u00e9 s mikroservisom interagova\u0165 zvonka na nejakej stabilnej b\u00e1ze, bez oh\u013eadu na vn\u00fatorn\u00e9 metamorf\u00f3zy. A dnes sa s vami podel\u00edme o na\u0161u problematiku vo\u013eby form\u00e1tu popisu zml\u00fav a zdie\u013eame n\u00e1jden\u00e9 artefakty. <\/p>\n

\"Tak
\n<\/a><\/noindex>
\nPr\u00edspevok pripravil Anna Melechova<\/a><\/noindex> a Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikroservisy.<\/b> Pri v\u00fdvoji Acronis Cyber Cloud sme si uvedomili, \u017ee sa im nedok\u00e1\u017eeme vyhn\u00fa\u0165. N\u00e1vrh mikroservisu nie je mo\u017en\u00fd bez formaliz\u00e1cie zmluvy, ktor\u00e1 predstavuje rozhranie mikroservisu.<\/p>\n

Ale ke\u010f produkt obsahuje viac ne\u017e jednu zlo\u017eku a v\u00fdvoj zmluvy sa st\u00e1va pravidelnou aktivitou, nevyhnutne za\u010dnete uva\u017eova\u0165 o optimaliz\u00e1cii procesu. St\u00e1va sa o\u010dividn\u00fdm, \u017ee rozhranie (zmluva) a implement\u00e1cia (mikroservis) si musia navz\u00e1jom zodpoveda\u0165, \u017ee r\u00f4zne zlo\u017eky by mali robi\u0165 rovnak\u00e9 veci rovnak\u00fdm sp\u00f4sobom, a \u017ee bez centralizovan\u00e9ho prij\u00edmania v\u0161etk\u00fdch t\u00fdchto rozhodnut\u00ed bude ka\u017ed\u00e9 t\u00edm n\u00faten\u00fd znova a znova str\u00e1ca\u0165 \u010das ich z\u00edskavan\u00edm. <\/p>\n

\"Tak
\nSch\u00e9ma mikroservisov Amazon z tweety<\/a><\/noindex> Wernera Vogelesa, CTO Amazon<\/i>
\nV \u010dom spo\u010d\u00edva dilema? De facto existuj\u00fa dva sp\u00f4soby interakcie mikroservisov \u2013 HTTP Rest a gRPC od spolo\u010dnosti Google. Aby sme sa nechceli zap\u00e1ja\u0165 do technologick\u00e9ho z\u00e1sobn\u00edka Google, zvolili sme HTTP Rest. Anot\u00e1cie k zmluv\u00e1m HTTP REST sa naj\u010dastej\u0161ie opisuj\u00fa jedn\u00fdm z dvoch form\u00e1tov: RAML a OAS, predt\u00fdm zn\u00e1my ako Swagger. Preto sa ka\u017ed\u00e9 v\u00fdvoj\u00e1rske t\u00edm stret\u00e1va s potrebou urobi\u0165 vo\u013ebu v prospech jedn\u00e9ho z \u0161tandardov. Ale ako sa uk\u00e1zalo, urobi\u0165 t\u00fato vo\u013ebu m\u00f4\u017ee by\u0165 ve\u013emi zlo\u017eit\u00e9.<\/p>\n

Na \u010do s\u00fa anot\u00e1cie potrebn\u00e9?<\/h3>\n

\nAnot\u00e1cia je potrebn\u00e1 na to, aby extern\u00fd pou\u017e\u00edvate\u013e mohol \u013eahko pochopi\u0165, \u010do m\u00f4\u017ee robi\u0165 s va\u0161ou slu\u017ebou cez jej HTTP rozhranie. To znamen\u00e1, \u017ee na z\u00e1kladnej \u00farovni by mala anot\u00e1cia obsahova\u0165 minim\u00e1lne zoznam dostupn\u00fdch zdrojov, ich HTTP met\u00f3d, tel\u00e1 dopytov, vymenovanie parametrov, uvedenie nevyhnutn\u00fdch a podporovan\u00fdch hlavi\u010diek, ako aj k\u00f3dov n\u00e1vratu a form\u00e1tov odpoved\u00ed. Mimoriadne d\u00f4le\u017eit\u00fdm prvkom anot\u00e1cie zmluvy je aj ich slovn\u00fd opis (\u201e\u010do sa stane, ak prid\u00e1te tento query parameter k dopytu?\u201c, \u201ev ak\u00fdch pr\u00edpadoch sa vr\u00e1ti k\u00f3d 400?\u201c)<\/p>\n

Napriek tomu, ke\u010f ide o v\u00fdvoj ve\u013ek\u00e9ho mno\u017estva mikroslu\u017eieb, je mo\u017en\u00e9 z\u00edska\u0165 \u010fal\u0161ie v\u00fdhody z nap\u00edsan\u00fdch anot\u00e1ci\u00ed. Napr\u00edklad, na z\u00e1klade RAML\/Swagger je mo\u017en\u00e9 generova\u0165 klientsky aj serverov\u00fd k\u00f3d na obrovskom mno\u017estve programovac\u00edch jazykov. Okrem toho je mo\u017en\u00e9 automaticky z\u00edskava\u0165 dokument\u00e1ciu k mikroslu\u017ebe a nahr\u00e1va\u0165 ju na v\u00e1\u0161 developer-portal : ).<\/p>\n

\"Tak
\nPr\u00edklad \u0161trukt\u00farovan\u00e9ho opisu zmluvy<\/i><\/p>\n

Zriedkavej\u0161ie sa stret\u00e1va prax testovania mikroslu\u017eieb na z\u00e1klade opisov zml\u00fav. Ak ste nap\u00edsali ako anot\u00e1ciu, tak aj komponent, m\u00f4\u017eete vytvori\u0165 autotest, ktor\u00fd over\u00ed primeranos\u0165 fungovania slu\u017eby s r\u00f4znymi typmi d\u00e1t na vstupe. Nevracia slu\u017eba k\u00f3d odpovede, ktor\u00fd nie je op\u00edsan\u00fd v anot\u00e1cii? Dok\u00e1\u017ee spr\u00e1vne spracova\u0165 zjavne nespr\u00e1vne d\u00e1ta?<\/p>\n

Navy\u0161e, kvalitn\u00e1 implement\u00e1cia nie len samotn\u00fdch zml\u00fav, ale aj n\u00e1strojov na vizualiz\u00e1ciu anot\u00e1ci\u00ed umo\u017e\u0148uje zjednodu\u0161i\u0165 pr\u00e1cu s mikroslu\u017ebou. T\u00fdm p\u00e1dom, ak architekt kvalitne op\u00edsal zmluvu, na jej z\u00e1klade dizajn\u00e9ri a v\u00fdvoj\u00e1ri bud\u00fa implementova\u0165 slu\u017ebu do in\u00fdch produktov bez dodato\u010dn\u00fdch \u010dasov\u00fdch n\u00e1kladov.<\/p>\n

Na pr\u00e1cu s dodato\u010dn\u00fdmi n\u00e1strojmi RAML aj OAS maj\u00fa mo\u017enos\u0165 prida\u0165 metad\u00e1ta, ktor\u00e9 nie s\u00fa predp\u00edsan\u00e9 \u0161tandardom (napr\u00edklad, takto sa to rob\u00ed v OAS<\/a><\/noindex>).<\/p>\n

Celkovo je pole pre kreativitu v aplik\u00e1cii zml\u00fav pre mikroslu\u017eby obrovsk\u00e9... aspo\u0148 teoreticky<\/p>\n

Porovnanie je\u017eka s hadom<\/h3>\n

\nV s\u00fa\u010dasnosti je prioritn\u00fdm smerom v\u00fdvoja v Acronis rozvoj Acronis Cyber Platform. Acronis Cyber Platform s\u00fa nov\u00e9 body integr\u00e1cie extern\u00fdch slu\u017eieb s Acronis Cyber Cloud a agendovou \u010das\u0165ou. Hoci na\u0161e intern\u00e9 API, op\u00edsan\u00e9 v RAML, n\u00e1m vyhovovali, potreba publikovania API op\u00e4\u0165 vyvolala ot\u00e1zku v\u00fdberu: ktor\u00fd \u0161tandard anot\u00e1ci\u00ed je pre na\u0161u pr\u00e1cu najlep\u0161\u00ed?<\/p>\n

Najprv sa zdalo, \u017ee existuj\u00fa dve rie\u0161enia \u2014 najroz\u0161\u00edrenej\u0161ie v\u00fdvojov\u00e9 r\u00e1mce RAML a Swagger (alebo OAS). Ale v skuto\u010dnosti sa uk\u00e1zalo, \u017ee alternat\u00edv je aspo\u0148 nie 2, ale 3 alebo viac.<\/p>\n

Na jednej strane je tu RAML \u2013 mocn\u00fd a efekt\u00edvny jazyk. V \u0148om je dobre implementovan\u00e1 hierarchia a dedenie, tak\u017ee tento form\u00e1t je vhodnej\u0161\u00ed pre ve\u013ek\u00e9 spolo\u010dnosti, ktor\u00e9 potrebuj\u00fa mno\u017estvo popisov \u2014 teda nie jeden produkt, ale mnoho mikroslu\u017eieb, ktor\u00e9 maj\u00fa spolo\u010dn\u00e9 \u010dasti kontraktov \u2014 sch\u00e9my autentifik\u00e1cie, rovnak\u00e9 typy d\u00e1t, tel\u00e1 ch\u00fdb.<\/p>\n

Ale v\u00fdvoj\u00e1r RAML, spolo\u010dnos\u0165 Mulesoft, sa pripojil k konzorciu Open API, ktor\u00e9 sa zaober\u00e1 rozvojom Swagger<\/a><\/noindex>. Preto sa v\u00fdvoj RAML pozastavil. Aby ste si predstavili form\u00e1t udalosti, predstavte si, \u017ee spr\u00e1vcovia hlavn\u00fdch komponentov Linuxu odi\u0161li pracova\u0165 do Microsoftu. Tak\u00e1 situ\u00e1cia vytv\u00e1ra predpoklady na pou\u017eitie Swagger, ktor\u00fd sa dynamicky vyv\u00edja a v poslednej \u2014 tretej verzii \u2014 takmer dobehne RAML z poh\u013eadu flexibility a funk\u010dnosti.<\/p>\n

Keby nebolo jedn\u00e9ho \"ale\"...<\/h3>\n

\nAko sa uk\u00e1zalo, \u010faleko nie v\u0161etky open-source n\u00e1stroje sa aktualizovali na verziu OAS 3.0. Pre mikroslu\u017eby na Go bude najkritickej\u0161\u00edm ch\u00fdbaj\u00faca adapt\u00e1cia go-swagger<\/a><\/noindex> na \u010derstv\u00fa verziu \u0161tandardu. Rozdiel medzi Swagger 2 a Swagger 3 je obrovsk\u00fd<\/a><\/noindex>. Napr\u00edklad v tretej verzii v\u00fdvoj\u00e1ri:<\/p>\n