{"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\/cs\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Tak co, RAML nebo OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

Ve dynamick\u00e9m sv\u011bt\u011b mikroslu\u017eeb se m\u016f\u017ee cokoliv zm\u011bnit \u2014 jak\u00e1koliv komponenta m\u016f\u017ee b\u00fdt p\u0159eprogramov\u00e1na v jin\u00e9m jazyce, s pou\u017eit\u00edm jin\u00fdch framework\u016f a architektury. Jedin\u011b smlouvy by m\u011bly z\u016fstat nem\u011bnn\u00e9, aby bylo mo\u017en\u00e9 s mikroslu\u017ebou interagovat z vn\u011bj\u0161ku na n\u011bjak\u00e9m st\u00e1l\u00e9m z\u00e1klad\u011b, bez ohledu na vnit\u0159n\u00ed metamorf\u00f3zy. Dnes se pod\u011bl\u00edme o na\u0161i probl\u00e9movou volbu form\u00e1tu popisu smluv a najdeme artefakty. <\/p>\n

\"Tak
\n<\/a><\/noindex>
\nP\u0159\u00edsp\u011bvek p\u0159ipravila Anna Melechova<\/a><\/noindex> a Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikroslu\u017eby.<\/b> P\u0159i v\u00fdvoji Acronis Cyber Cloud jsme si uv\u011bdomili, \u017ee se jim nelze vyhnout. A navrhov\u00e1n\u00ed mikroslu\u017eby je nemo\u017en\u00e9 bez formalizace smlouvy, kter\u00e1 p\u0159edstavuje rozhran\u00ed mikroslu\u017eby.<\/p>\n

Ale kdy\u017e v produktu je v\u00edce ne\u017e jedna komponenta a v\u00fdvoj smlouvy se st\u00e1v\u00e1 pravidelnou \u010dinnost\u00ed, nevyhnuteln\u011b za\u010dnete uva\u017eovat o optimalizaci procesu. St\u00e1v\u00e1 se z\u0159ejm\u00fdm, \u017ee rozhran\u00ed (smlouva) a implementace (mikroslu\u017eba) by si m\u011bly odpov\u00eddat, \u017ee r\u016fzn\u00e9 komponenty by m\u011bly d\u011blat stejn\u00e9 v\u011bci stejn\u011b, a \u017ee bez centralizovan\u00e9ho rozhodov\u00e1n\u00ed o t\u011bchto z\u00e1le\u017eitostech bude ka\u017ed\u00e9 t\u00fdmu neust\u00e1le tr\u00e1vit \u010das jejich z\u00edsk\u00e1v\u00e1n\u00edm znovu a znovu. <\/p>\n

\"Tak
\nSch\u00e9ma mikroslu\u017eeb Amazon z tweety<\/a><\/noindex> Wernera Vogeliusa, CTO Amazon<\/i>
\nV \u010dem spo\u010d\u00edv\u00e1 dilema? De facto existuj\u00ed dva zp\u016fsoby interakce mikroslu\u017eeb \u2013 HTTP Rest a gRPC od spole\u010dnosti Google. Necht\u011bj\u00edce se zapl\u00e9st do technologie Google, jsme zvolili HTTP Rest. Anotace smluv HTTP REST se nej\u010dast\u011bji popisuj\u00ed jedn\u00edm ze dvou form\u00e1t\u016f: RAML a OAS, d\u0159\u00edve zn\u00e1m\u00fd jako Swagger. Proto se ka\u017ed\u00fd t\u00fdm v\u00fdvoj\u00e1\u0159\u016f setk\u00e1v\u00e1 s pot\u0159ebou zvolit si jeden ze standard\u016f. Jak se uk\u00e1zalo, u\u010dinit tuto volbu m\u016f\u017ee b\u00fdt velmi obt\u00ed\u017en\u00e9.<\/p>\n

Pro\u010d jsou anotace pot\u0159ebn\u00e9?<\/h3>\n

\nAnotace je pot\u0159eba, aby se extern\u00ed u\u017eivatel mohl snadno orientovat v tom, co m\u016f\u017ee se sv\u00fdm slu\u017ebou prov\u00e1d\u011bt prost\u0159ednictv\u00edm jej\u00edho HTTP rozhran\u00ed. To znamen\u00e1, \u017ee na z\u00e1kladn\u00ed \u00farovni by anotace m\u011bla obsahovat minim\u00e1ln\u011b seznam dostupn\u00fdch zdroj\u016f, jejich HTTP metody, t\u011bla \u017e\u00e1dost\u00ed, v\u00fd\u010det parametr\u016f, specifikaci pot\u0159ebn\u00fdch a podporovan\u00fdch hlavi\u010dek, jako\u017e i k\u00f3dy n\u00e1vratu a form\u00e1ty odpov\u011bd\u00ed. Krajn\u011b d\u016fle\u017eit\u00fdm prvkem anotace kontraktu je tak\u00e9 jejich slovn\u00ed popis (\u201eco se stane, kdy\u017e p\u0159id\u00e1te tento dotazov\u00fd parametr k \u017e\u00e1dosti?\u201c, \u201ev jak\u00e9m p\u0159\u00edpad\u011b se vr\u00e1t\u00ed k\u00f3d 400?\u201c)<\/p>\n

Nicm\u00e9n\u011b, pokud jde o v\u00fdvoj velk\u00e9ho mno\u017estv\u00ed mikroslu\u017eeb, chceme z napsan\u00fdch anotac\u00ed z\u00edskat dal\u0161\u00ed u\u017eitek. Nap\u0159\u00edklad na z\u00e1klad\u011b RAML\/Swagger m\u016f\u017eeme generovat jak klientsk\u00fd, tak serverov\u00fd k\u00f3d v obrovsk\u00e9m mno\u017estv\u00ed programovac\u00edch jazyk\u016f. A m\u016f\u017eeme tak\u00e9 automaticky z\u00edskat dokumentaci k mikroslu\u017eb\u011b a nahr\u00e1t ji na v\u00e1\u0161 developersk\u00fd port\u00e1l :).<\/p>\n

\"Tak
\nP\u0159\u00edklad strukturovan\u00e9ho popisu kontraktu<\/i><\/p>\n

M\u00e9n\u011b \u010dastou prax\u00ed je testov\u00e1n\u00ed mikroslu\u017eeb na z\u00e1klad\u011b popis\u016f kontrakt\u016f. Pokud jste napsali jak anotaci, tak komponent, m\u016f\u017eete vytvo\u0159it automatizovan\u00fd test, kter\u00fd zkontroluje adekv\u00e1tnost fungov\u00e1n\u00ed slu\u017eby s r\u016fzn\u00fdmi typy dat na vstupu. Nevrac\u00ed slu\u017eba k\u00f3d odpov\u011bdi, kter\u00fd nen\u00ed pops\u00e1n v anotaci? Bude schopna spr\u00e1vn\u011b zpracovat zjevn\u011b chybn\u00e1 data?<\/p>\n

V\u00edce ne\u017e to, kvalitn\u00ed implementace nejen samotn\u00fdch kontrakt\u016f, ale tak\u00e9 n\u00e1stroj\u016f pro vizualizaci anotac\u00ed usnad\u0148uje pr\u00e1ci s mikroslu\u017ebou. To znamen\u00e1, \u017ee pokud architekt kvalitn\u011b popsal kontrakt, na jeho z\u00e1klad\u011b budou design\u00e9\u0159i a v\u00fdvoj\u00e1\u0159i implementovat slu\u017ebu do jin\u00fdch produkt\u016f bez dodate\u010dn\u00fdch \u010dasov\u00fdch n\u00e1klad\u016f.<\/p>\n

Pro pr\u00e1ci s dal\u0161\u00edmi n\u00e1stroji maj\u00ed jak RAML, tak OAS mo\u017enost p\u0159id\u00e1vat metadata, kter\u00e1 nejsou ve standardu zahrnuta (nap\u0159\u00edklad, jak se to d\u011bl\u00e1 v OAS<\/a><\/noindex>).<\/p>\n

Obecn\u011b plat\u00ed, \u017ee prostor pro kreativitu v aplikaci kontrakt\u016f pro mikroslu\u017eby je obrovsk\u00fd\u2026 alespo\u0148 teoreticky<\/p>\n

Srovn\u00e1n\u00ed je\u017eka s u\u017eovkou<\/h3>\n

\nV sou\u010dasn\u00e9 dob\u011b je prioritn\u00edm sm\u011brem v\u00fdvoje v Acronis v\u00fdvoj Acronis Cyber Platform. Acronis Cyber Platform \u2013 to jsou nov\u00e1 m\u00edsta integrace extern\u00edch slu\u017eeb s Acronis Cyber Cloud a agentn\u00ed \u010d\u00e1st\u00ed. A\u010dkoli na\u0161e intern\u00ed API, popsan\u00e1 v RAML, n\u00e1s uspokojovala, pot\u0159eba zve\u0159ejn\u011bn\u00ed API znovu vyvolala ot\u00e1zku v\u00fdb\u011bru: kter\u00fd standard anotac\u00ed je pro na\u0161i pr\u00e1ci lep\u0161\u00ed?<\/p>\n

Na za\u010d\u00e1tku se zd\u00e1lo, \u017ee existuj\u00ed dv\u011b \u0159e\u0161en\u00ed \u2013 nejroz\u0161\u00ed\u0159en\u011bj\u0161\u00ed v\u00fdvoj RAML a Swagger (nebo OAS). Ale ve skute\u010dnosti se uk\u00e1zalo, \u017ee alternativ je minim\u00e1ln\u011b 3 nebo v\u00edce.<\/p>\n

Na jedn\u00e9 stran\u011b je tu RAML \u2013 mocn\u00fd a efektivn\u00ed jazyk. M\u00e1 dob\u0159e implementovanou hierarchii a d\u011bdi\u010dnost, tak\u017ee tento form\u00e1t je v\u00edce vhodn\u00fd pro velk\u00e9 spole\u010dnosti, kter\u00e9 pot\u0159ebuj\u00ed hodn\u011b popis\u016f \u2013 tedy ne jeden produkt, ale mnoho mikroservis\u016f, kter\u00e9 maj\u00ed spole\u010dn\u00e9 \u010d\u00e1sti kontrakt\u016f \u2013 sch\u00e9mata autentizace, stejn\u00e9 typy dat, t\u011bla chyb.<\/p>\n

Ale v\u00fdvoj\u00e1\u0159 RAML, spole\u010dnost Mulesoft, se p\u0159ipojil k konsorciu Open API, kter\u00e9 se zab\u00fdv\u00e1 v\u00fdvojem Swagger<\/a><\/noindex>. Proto RAML pozastavil sv\u016fj v\u00fdvoj. P\u0159edstavte si form\u00e1t ud\u00e1losti jako situaci, kdy hlavn\u00ed \u00fadr\u017eb\u00e1\u0159i hlavn\u00edch komponent Linuxu ode\u0161li pracovat do Microsoftu. Takov\u00e1 situace vytv\u00e1\u0159\u00ed podm\u00ednky pro pou\u017eit\u00ed Swaggeru, kter\u00fd se dynamicky vyv\u00edj\u00ed a v posledn\u00ed \u2013 t\u0159et\u00ed verzi \u2013 t\u00e9m\u011b\u0159 doh\u00e1n\u00ed RAML co do flexibility a funk\u010dnosti.<\/p>\n

Kdyby nebylo jednoho ale\u2026<\/h3>\n

\nJak se uk\u00e1zalo, daleko ne v\u0161echny open-source n\u00e1stroje se aktualizovaly na verzi OAS 3.0. Pro mikroservisy na Go bude nejkriti\u010dt\u011bj\u0161\u00ed absence adaptace go-swagger<\/a><\/noindex> na novou verzi standardu. Rozd\u00edl mezi Swagger 2 a Swagger 3 je v\u0161ak ohromn\u00fd<\/a><\/noindex>. Nap\u0159\u00edklad v t\u0159et\u00ed verzi v\u00fdvoj\u00e1\u0159i:<\/p>\n