🥇Все пак RAML или OAS (Swagger)?

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

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

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

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

Схема на микросервисите на Amazon от туит на Вернер Вогелис, СТО на 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). Но в действителност се оказа, че алтернативите са поне не две, а три или повече.

От една страна имаме 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. Все пак, по време на нашето проучване, инструментът все още беше ИЗКЛЮЧИТЕЛНО недобре разработен и неподходящ за употреба. Разработчиците създават нещо като IR, което ще им позволи в бъдеще бързо да добавят нови стандарти. Но засега всичко това просто не работи.

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

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

Заключение

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

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

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

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

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