🥇И така, RAML или OAS (Swagger)?

В динамичния свят на микросервисите всичко може да се промени - всеки компонент може да бъде пренаписан на друг език, използвайки различни фреймворкове и архитектури. Единственото, което трябва да остане непроменено, са контрактите, за да може да се взаимодейства с микросервиса по постоянен начин, независимо от вътрешните метаморфози. Днес ще разкажем за нашия проблем с избора на формат за описание на контрактите и ще споделим намерените артефакти.

Постът е подготвен от Анна Мелехова и Владимир Лапатин

Микросервиси. При разработката на Acronis Cyber Cloud разбрахме, че не можем да се отървем от тях. Проектирането на микросервиз е невъзможно без формализиране на контракта, който представлява интерфейса на микросервиза.

Но когато в продукта има повече от един компонент и разработването на контракта става редовна активност, неволно започваш да се замисляш за оптимизация на процеса. Очевидно е, че интерфейсът (контрактът) и имплементацията (микросервизът) трябва да си съответстват, че различните компоненти трябва да извършват едни и същи неща по един и същ начин и че без централизирано вземане на всички тези решения всяка команда ще трябва отново и отново да отделя време за тяхното вземане.

Схемата на микросервисите на Amazon от твит на Вернер Вогелис, CTO на Amazon
Каква е дилемата? Де факто съществуват два начина за взаимодействие на микросервисите - HTTP Rest и gRPC от Google. Не желаейки да бъдем въвлечени в технологичния стек на Google, избрахме HTTP Rest. Анотациите на контрактите за HTTP REST най-често се описват с един от двата формата: RAML и OAS, преди известен като Swagger. Следователно всяка разработваща екип е изправен пред необходимостта да направи избор в полза на един от стандартите. Но, както се оказа, този избор може да бъде много труден.

Защо са нужни анотации?

Анотация е нужна, за да може външният потребител лесно да разбере какво може да се прави с вашия сервис чрез неговия HTTP интерфейс. Тоест, на базово ниво анотацията трябва да съдържа поне списък на наличните ресурси, техните HTTP методи, тела на заявките, изброяване на параметри, указание на задължителни и поддържани заглавия, както и кодове за връщане и формати на отговори. Изключително важен елемент на анотацията на договора е и тяхното словесно описание ("какво ще се случи, ако добавите този query параметър към заявката?", "в какъв случай ще се върне код 400?")

Въпреки това, когато става въпрос за разработка на голям брой микросервизи, човек иска да извлече допълнителни ползи от написаните анотации. Например, на базата на RAML/Swagger може да се генерира както клиентски, така и сървърен код на огромен брой програмни езици. Освен това, може автоматично да се получи документация за микросервиза и да я качите на вашия developer портал :)

Пример за структурирано описание на договора

По-рядко се среща практиката за тестване на микросервизи на базата на описания на договори. Ако сте написали и анотация, и компонент, можете да създадете автотест, който проверява адекватността на работата на сървиса с различни типове данни на входа. Връща ли сервизът код на отговор, който не е описан в анотацията? Ще може ли коректно да обработи явно неверни данни?

По-важното е, че качествената реализация не само на самите договори, но и на инструментариума за визуализация на анотациите позволява да се опрости работата с микросервиза. Тоест, ако архитектът качествено е описал договора, на неговата основа дизайнерите и разработчиците ще внедрят сервиса в други продукти без допълнителни времеви разходи.

За работа с допълнителни инструменти и RAML, и OAS имат възможност за добавяне на метаданни, непредвидени от стандарта (например, така се прави в OAS).

В общи линии, полето за творчество в приложението на договорите за микросервизи е огромно... поне теоретично

Сравнение на таралеж с усойница

В момента основна насока на разработка в Acronis е развитието на Acronis Cyber Platform. Acronis Cyber Platform представлява нови точки за интеграция на трети страни с Acronis Cyber Cloud и агентската част. Въпреки че нашите вътрешни API, описани в RAML, ни удовлетворяваха, необходимостта от публикуване на API отново повдигна въпроса за избора: кой стандарт за анотации е най-добрият за нашата работа?

Първоначално изглеждаше, че има две решения — най-разпространените разработки RAML и Swagger (или OAS). Но всъщност се оказа, че алтернативите са поне 3 или повече.

От една страна, имаме RAML – мощен и ефективен език. В него е добре реализирана йерархия и наследяване, така че този формат е по-подходящ за големи компании, които имат много описания — тоест не един продукт, а много микросервизи с общи части от договорите — схеми за аутентификация, еднакви типове данни, тела на грешки.

Но разработчикът на RAML, компания Mulesoft, се присъедини към консорциума Open API, който се занимава с развитието на Swagger. Поради това RAML спря развитието си. За да си представите формата на събитието, представете си, че поддържачите на основните компоненти на Linux са отишли да работят в Microsoft. Такава ситуация създава предпоставки за използването на Swagger, който динамично се развива и в последната — трета версия — почти настигна RAML по гъвкавост и функционалност.

Ако не беше едно но...

Както се оказа, далеч не всички open-source инструменти са обновени до версия OAS 3.0. За микросервизите на Go най-критично ще бъде отсъствието на адаптация на go-swagger към новата версия на стандарта. Обаче разликата между Swagger 2 и Swagger 3 — е огромна. Например, в третата версия разработчиците:

подобряват описанието на схемите за аутентификация
завършват подкрепата на JSON Schema
разширяват възможността за добавяне на примери

Ситуацията се оказва интересна: при избора на стандарт трябва да разглеждаме RAML, Swagger 2 и Swagger 3 като отделни алтернативи. При това само Swagger 2 има добра поддръжка на инструменти с OpenSource. RAML е много гъвкав… и сложен, а Swagger 3 слабо се поддържа от общността, така че ще трябва да ползвате инструменти от собствена разработка или търговски решения, които, като правило, са доста скъпи.

При това, ако в Swagger съществуват много приятни възможности, като готов портал editor.swagger.io, на който може да се качи анотация и да се получи нейната визуализация с подробни описания, връзки и зависимости, но за по-фундаментален и по-малко потребителски ориентиран RAML такава възможност няма. Да, може да се потърси нещо сред проектите в GitHub, да се намери аналог и да се разграничи самостоятелно. Въпреки това, в крайна сметка някой трябва да поддържа портала, което не е толкова удобно за базово използване или тестови нужди. Освен това, swagger е по-

безпринципен или либерален - може да се генерира от коментари в кода, което, разбира се, противоречи на принципа API first и не се поддържа от нито една утилита на RAML, Започнахме да работим с RAML, като с по-гъвкав език, и накрая много от нещата трябваше да направим ръчно. Например, в един от проектите се използва утилита

ramlfications

в юнит-тестовете, която поддържа само RAML 0.8. Така че се наложи да добавим приставки, за да може утилитата да "усвоява" RAML версии 1.0.

Но нужно ли е да избираме?

След като се запознахме с дописването на екосистемата от решения под RAML, стигнахме до извода, че трябва да конвертираме RAML в Swagger 2 и вече в него да провеждаме цялата автоматизация, проверка, тестване и последваща оптимизация. Това е добър начин да използваме едновременно и гъвкавостта на RAML, и инструментариума на общността от Swagger. За решаване на тази задача съществуват два инструмента с отворен код, които трябва да осигурят конвертиране на договорите:
oas-raml-converter – вече неподдържана утилита. В процеса на работа с нея установихме, че има редица проблеми със сложни RAML-и, които са "разпилени" в голям брой файлове. Тази програма е написана на JavaScript и извършва рекурсивно обход на синтактичното дърво. Поради динамичната типизация, разбирането на този код става сложно, така че решихме да не губим време за писане на пачове на умиращата утилита. webapi-parser — инструмент от същата компания, който претендира, че е готов да конвертира всичко и всякак, и то в двете посоки. Към днешна дата е обявена поддръжка на RAML 0.8, RAML 1.0 и Swagger 2.0. Въпреки това, в момента на нашето проучване, утилитата все още беше КРАЙНО, което ще им позволи в бъдеще да добавят нови стандарти бързо. Но за момента всичко това просто не работи.

И това не са всички трудности, с които се сблъскахме. Една от стъпките в нашия пайплайн е проверката на това, дали RAML от хранилището е коректен спрямо спецификацията. Изпробвахме няколко инструмента. Учудващо е, но всички те се оплакваха от нашите анотации на различни места и с напълно различни неуместни думи. И не винаги по същество :).

В крайна сметка се спряхме на вече остарял проект, който също има редица проблеми (понякога пада без причина, има проблеми при работа с регулярни изрази). Така че не намерихме начин да решим задачите по валидация и конвертиране на база безплатни инструменти и решихме да се възползваме от комерсиален инструмент. В бъдеще, когато OpenSource средствата станат по-усъвършенствани, решаването на тази задача, може би, ще стане по-лесно. А за момента времевите и трудовите разходи за 'дооправяне' ни се сториха по-значителни от разходите за комерсиалната услуга.

Заключение

След всичко това, ни се прииска да споделим опит и да подчертаем, че преди да изберете инструмент за описване на договори, трябва ясно да определите какво искате от него и какъв бюджет сте готови да вложите. Ако забравим за OpenSource, вече в момента съществуват много услуги и продукти, които ще помогнат за проверка, конвертиране и валидация. Но те са скъпи, а понякога - много скъпи. За голямо предприятие тези разходи са поносимо, но за стартап могат да станат значителна тежест.

Определете набора от инструменти, които ще използвате по-късно. Например, ако просто трябва да покажете договора, по-лесно ще бъде да използвате Swagger 2, който има красив API, докато в RAML ще трябва сами да поддържате и управлявате услугата.
Колкото повече ще имате задачи, толкова по-широка ще бъде нуждата от инструменти, а те са различни за различни платформи и е добре веднага да се запознаете с наличните версии, за да направите избор, който минимализира разходите ви в бъдеще.

Но е важно да признаем, че всички екосистеми, които съществуват днес, не са съвършени. И затова, ако в компанията има фенове, които обичат да работят с RAML, защото "той позволява по-гъвкаво изразяване на мислите", или обратно, предпочитат Swagger, защото "е по-разбираем" — най-добре е да ги оставим да работят в това, с което са свикнали и искат, защото инструментариумът на всеки от форматите изисква доработка.

Що се отнася до нашия опит, в следващите постове ще разкажем какви — статични и динамични проверки извършваме на базата на нашата RAML-Swagger архитектура, както и каква документация генерираме от договорите и как всичко това работи.

Само регистрирани потребители могат да участват в анкетата. Влезте, моля.