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

W dynamicznym \u015bwiecie mikroserwis\u00f3w wszystko mo\u017ce si\u0119 zmieni\u0107 \u2014 ka\u017cdy komponent mo\u017cna napisa\u0107 w innym j\u0119zyku, korzystaj\u0105c z innych framework\u00f3w i architektury. Nie mog\u0105 zmienia\u0107 si\u0119 jedynie kontrakty, aby mo\u017cna by\u0142o w jaki\u015b sta\u0142y spos\u00f3b interagowa\u0107 z mikroserwisem, niezale\u017cnie od wewn\u0119trznych metamorfoz. Dzi\u015b opowiemy o naszym problemie z wyborem formatu opisu kontrakt\u00f3w i podzielimy si\u0119 znalezionymi artefaktami. <\/p>\n

\"RAML
\n<\/a><\/noindex>
\nPost przygotowa\u0142 Anna Melekhova<\/a><\/noindex> i W\u0142odzimierz Lapatin<\/a><\/noindex> <\/p>\n

Mikroserwisy.<\/b> Podczas rozwoju Acronis Cyber Cloud zrozumieli\u015bmy, \u017ce nie mo\u017cemy ich unikn\u0105\u0107. A projektowanie mikroserwisu jest niemo\u017cliwe bez sformalizowania kontraktu, kt\u00f3ry stanowi interfejs mikroserwisu.<\/p>\n

Jednak gdy w produkcie znajduje si\u0119 wi\u0119cej ni\u017c jeden komponent, a tworzenie kontraktu staje si\u0119 regularn\u0105 aktywno\u015bci\u0105, zaczynasz si\u0119 zastanawia\u0107 nad optymalizacj\u0105 procesu. Oczywiste staje si\u0119, \u017ce interfejs (kontrakt) i implementacja (mikroserwis) musz\u0105 si\u0119 nawzajem zgadza\u0107, r\u00f3\u017cne komponenty musz\u0105 wykonywa\u0107 te same czynno\u015bci w ten sam spos\u00f3b, a bez centralnego podejmowania wszystkich tych decyzji ka\u017cda dru\u017cyna b\u0119dzie zmuszona wci\u0105\u017c i wci\u0105\u017c traci\u0107 czas na ich pozyskiwanie. <\/p>\n

\"RAML
\nSchemat mikroserwis\u00f3w Amazon z tweeta<\/a><\/noindex> Wernera Vogelsa, CTO Amazon<\/i>
\nNa czym polega dylemat? De facto istniej\u0105 dwa sposoby interakcji mikroserwis\u00f3w \u2013 HTTP Rest i gRPC firmy Google. Nie chc\u0105c by\u0107 zaanga\u017cowanym w technologi\u0119 Google, wybrali\u015bmy HTTP Rest. Adnotacje do kontrakt\u00f3w HTTP REST najcz\u0119\u015bciej opisuje si\u0119 jednym z dw\u00f3ch format\u00f3w: RAML i OAS, wcze\u015bniej znanym jako Swagger. Dlatego ka\u017cda dru\u017cyna deweloper\u00f3w staje przed konieczno\u015bci\u0105 wyboru jednego z standard\u00f3w. Jak si\u0119 okaza\u0142o, podj\u0119cie tego wyboru mo\u017ce by\u0107 bardzo trudne.<\/p>\n

Po co s\u0105 adnotacje?<\/h3>\n

\nAdnotacja jest potrzebna, aby zewn\u0119trzny u\u017cytkownik m\u00f3g\u0142 \u0142atwo zrozumie\u0107, co mo\u017cna robi\u0107 z Twoim serwisem za po\u015brednictwem jego interfejsu HTTP. Oznacza to, \u017ce na podstawowym poziomie adnotacja powinna zawiera\u0107 przynajmniej list\u0119 dost\u0119pnych zasob\u00f3w, ich metod HTTP, cia\u0142 \u017c\u0105da\u0144, wyliczenie parametr\u00f3w, wskazanie wymaganych i wspieranych nag\u0142\u00f3wk\u00f3w, a tak\u017ce kod\u00f3w odpowiedzi i format\u00f3w odpowiedzi. Niezwykle wa\u017cnym elementem adnotacji kontraktu jest r\u00f3wnie\u017c ich opis s\u0142owny (\u201eco si\u0119 stanie, je\u015bli dodasz ten parametr zapytania do \u017c\u0105dania?\u201d, \u201ew jakiej sytuacji zostanie zwr\u00f3cony kod 400?\u201d)<\/p>\n

Jednak gdy m\u00f3wimy o rozwijaniu du\u017cej liczby mikroserwis\u00f3w, chcemy wyci\u0105gn\u0105\u0107 dodatkow\u0105 korzy\u015b\u0107 z napisanych adnotacji. Na przyk\u0142ad, na podstawie RAML\/Swagger mo\u017cna generowa\u0107 zar\u00f3wno kod kliencki, jak i serwerowy w ogromnej liczbie j\u0119zyk\u00f3w programowania. Mo\u017cna r\u00f3wnie\u017c automatycznie uzyskiwa\u0107 dokumentacj\u0119 mikroserwisu i umieszcza\u0107 j\u0105 na swoim portalu dewelopera :)<\/p>\n

\"RAML
\nPrzyk\u0142ad ustrukturyzowanego opisu kontraktu<\/i><\/p>\n

Rzadziej spotyka si\u0119 praktyk\u0119 testowania mikroserwis\u00f3w na podstawie opis\u00f3w kontrakt\u00f3w. Je\u015bli napisa\u0142e\u015b zar\u00f3wno adnotacj\u0119, jak i komponent, mo\u017cna stworzy\u0107 autotest, kt\u00f3ry sprawdzi adekwatno\u015b\u0107 dzia\u0142ania serwisu z r\u00f3\u017cnymi typami danych wej\u015bciowych. Czy serwis nie zwraca kodu odpowiedzi, kt\u00f3ry nie jest opisany w adnotacji? Czy b\u0119dzie w stanie poprawnie obs\u0142u\u017cy\u0107 oczywi\u015bcie b\u0142\u0119dne dane?<\/p>\n

Co wi\u0119cej, jako\u015bciowe wdro\u017cenie nie tylko samych kontrakt\u00f3w, ale tak\u017ce narz\u0119dzi do wizualizacji adnotacji pozwala upro\u015bci\u0107 prac\u0119 z mikroserwisem. Oznacza to, \u017ce je\u015bli architekt dobrze opisa\u0142 kontrakt, to na jego podstawie projektanci i programi\u015bci b\u0119d\u0105 wdra\u017ca\u0107 serwis w inne produkty bez dodatkowych nak\u0142ad\u00f3w czasowych.<\/p>\n

Dla pracy dodatkowych narz\u0119dzi zar\u00f3wno RAML, jak i OAS maj\u0105 mo\u017cliwo\u015b\u0107 dodawania metadanych, kt\u00f3re nie s\u0105 przewidziane przez standard (na przyk\u0142ad, tak robi si\u0119 w OAS<\/a><\/noindex>).<\/p>\n

Og\u00f3lnie rzecz bior\u0105c, pole dla kreatywno\u015bci w zastosowaniu kontrakt\u00f3w dla mikroserwis\u00f3w \u2014 ogromne\u2026 przynajmniej teoretycznie<\/p>\n

Por\u00f3wnanie je\u017ca z w\u0119\u017cem<\/h3>\n

\nObecnie priorytetowym kierunkiem rozwoju w Acronis jest rozw\u00f3j Acronis Cyber Platform. Acronis Cyber Platform to nowe punkty integracji zewn\u0119trznych us\u0142ug z Acronis Cyber Cloud oraz cz\u0119\u015bci\u0105 agenta. Cho\u0107 nasze wewn\u0119trzne API, opisane w RAML, s\u0105 zadowalaj\u0105ce, konieczno\u015b\u0107 publikacji API ponownie wywo\u0142a\u0142a pytanie: kt\u00f3ry standard anotacji jest najlepszy do naszej pracy?<\/p>\n

Pocz\u0105tkowo wydawa\u0142o si\u0119, \u017ce istniej\u0105 dwa rozwi\u0105zania \u2014 to najcz\u0119\u015bciej stosowane opracowania RAML i Swagger (lub OAS). Okaza\u0142o si\u0119 jednak, \u017ce alternatyw jest co najmniej nie 2, a 3 lub wi\u0119cej.<\/p>\n

Z jednej strony mamy RAML \u2014 pot\u0119\u017cny i efektywny j\u0119zyk. Dobrze zrealizowana jest w nim hierarchia i dziedziczenie, wi\u0119c ten format lepiej nadaje si\u0119 dla du\u017cych firm, kt\u00f3re potrzebuj\u0105 wielu opis\u00f3w \u2014 to znaczy nie jednego produktu, a wielu mikrous\u0142ug, kt\u00f3re maj\u0105 wsp\u00f3lne cz\u0119\u015bci kontrakt\u00f3w \u2014 schematu autoryzacji, takie same typy danych, cia\u0142a b\u0142\u0119d\u00f3w.<\/p>\n

Jednak tw\u00f3rca RAML, firma Mulesoft, do\u0142\u0105czy\u0142a do konsorcjum Open API, kt\u00f3re zajmuje si\u0119 rozwojem Swagger<\/a><\/noindex>. Dlatego rozw\u00f3j RAML zosta\u0142 wstrzymany. Aby wyobrazi\u0107 sobie format zdarzenia, wyobra\u017a sobie, \u017ce g\u0142\u00f3wni maintainerzy komponent\u00f3w Linux przeszli do pracy w Microsoft. Taka sytuacja stwarza przes\u0142anki do u\u017cywania Swagger, kt\u00f3ry rozwija si\u0119 dynamicznie i w ostatniej \u2014 trzeciej wersji \u2014 praktycznie dogania RAML pod wzgl\u0119dem elastyczno\u015bci i funkcjonalno\u015bci.<\/p>\n

Gdyby nie jeden ale...<\/h3>\n

\nOkaza\u0142o si\u0119, \u017ce nie wszystkie narz\u0119dzia open-source zaktualizowa\u0142y si\u0119 do wersji OAS 3.0. Dla mikrous\u0142ug w Go kluczowe b\u0119dzie brak adaptacji go-swagger<\/a><\/noindex> do \u015bwie\u017cej wersji standardu. Jednak r\u00f3\u017cnica mi\u0119dzy Swagger 2 a Swagger 3 \u2014 jest ogromna.<\/a><\/noindex>Na przyk\u0142ad w trzeciej wersji deweloperzy:<\/p>\n