Значи, дали е тоа RAML или OAS (Swagger)?

Во динамичниот свет на микросервисите, сè може да се промени - секоја компонента може да се преработи на различен јазик, користејќи различни рамки и архитектура. Само договорите треба да останат непроменети за да може микросервисот да биде во интеракција однадвор на некоја трајна основа, без оглед на внатрешните метаморфози. И денес ќе зборуваме за нашиот проблем за избор на формат за опишување договори и споделување на артефактите што ги најдовме.

Објавата е подготвена Ана Мелехова и Владимир лапатин

Микроуслуги. Кога го развивавме Acronis Cyber ​​Cloud, сфативме дека не можеме да им избегаме. И дизајнирањето на микросервис е невозможно без формализирање на договорот, кој го претставува интерфејсот на микросервисот.

Но, кога производот содржи повеќе од една компонента, а развојот на договор станува редовна активност, не можете а да не почнете да размислувате за оптимизација на процесот. Станува очигледно дека интерфејсот (договорот) и имплементацијата (микросервис) мора да одговараат едни на други, дека различните компоненти мора да ги прават истите работи на ист начин и дека без централизирано одлучување за сите овие одлуки, секој тим ќе биде принуден да поминуваат време повторно и повторно за да ги добиете.

Дијаграм за микросервис на Амазон од твит Вернер Вогелис, CTO на Amazon
Која е дилемата? Де факто, постојат два начини за интеракција со микросервисите - HTTP Rest и gRPC од Google. Не сакајќи да се заглавиме во технолошкиот куп на Google, избравме HTTP Rest. Прибелешките за договорот HTTP REST најчесто се опишуваат во еден од двата формати: RAML и OAS, порано познати како Swagger. Затоа, секој развојен тим се соочува со потребата да избере еден од стандардите. Но, како што се испостави, правењето на овој избор може да биде многу тешко.

Зошто се потребни прибелешки?

Прибелешката е потребна за да може надворешен корисник лесно да сфати што може да се направи со вашата услуга преку нејзиниот HTTP интерфејс. Односно, на основно ниво, прибелешката мора да содржи најмалку листа на достапни ресурси, нивните HTTP методи, тела на барања, листа на параметри, индикација за потребните и поддржани заглавија, како и кодови за враќање и формати на одговор. Исклучително важен елемент на прибелешката на договорот е нивниот вербален опис („што ќе се случи ако го додадете овој параметар за барање на барањето?“, „Во кој случај ќе се врати кодот 400?“)

Меѓутоа, кога станува збор за развој на голем број микроуслуги, сакате да извлечете дополнителна вредност од напишаните прибелешки. На пример, врз основа на RAML/Swagger, можете да генерирате и клиентски и сервер код на огромен број програмски јазици. Можете исто така автоматски да добивате документација за микросервисот и да ја прикачите на вашиот програмер-портал :).

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

Поретки е практиката на тестирање на микроуслуги врз основа на описите на договорите. Ако сте напишале и прибелешка и компонента, тогаш можете да креирате автотест што ја проверува адекватноста на услугата со различни типови на влезни податоци. Дали услугата враќа код за одговор што не е опишан во прибелешката? Дали ќе може правилно да обработува очигледно неточни податоци?

Покрај тоа, висококвалитетното спроведување не само на самите договори, туку и на алатките за визуелизирање на прибелешките овозможува да се поедностави работата со микросервисот. Односно, ако архитектот квалитативно го опишал договорот, врз основа на него, дизајнерите и програмерите ќе ја имплементираат услугата во други производи без дополнителни временски трошоци.

За да се овозможат дополнителни алатки, и RAML и OAS имаат можност да додаваат метаподатоци што не се предвидени со стандардот (на пример, вака се прави во OAS).

Општо земено, просторот за креативност при користење на договори за микроуслуги е огромен... барем теоретски.

Споредба на еж со змија

Во моментов, приоритетната област за развој во Acronis е развојот на Сајбер-платформата Acronis. Acronis Cyber ​​​​Platform е нови точки на интеграција на услуги од трети страни со Acronis Cyber ​​​​Cloud и делот за агенти. Иако бевме задоволни со нашите внатрешни API опишани во RAML, потребата од објавување на API повторно го покрена прашањето за избор: кој стандард за прибелешки е најдобро да се користи за нашата работа?

Првично, се чинеше дека има две решенија - најчестите случувања беа RAML и Swagger (или OAS). Но, всушност се покажа дека има барем не 2 алтернативи, туку 3 или повеќе.

Од една страна има RAML - моќен и ефикасен јазик. Добро ги имплементира хиерархијата и наследувањето, така што овој формат е посоодветен за големи компании на кои им требаат многу описи - односно не еден производ, туку многу микросервиси кои имаат заеднички делови од договорите - шеми за автентикација, исти типови податоци, тела за грешки .

Но, развивачот на RAML, Mulesoft, се приклучи на конзорциумот Open API, кој развива Свагер. Затоа, RAML го суспендираше својот развој. За да го замислите форматот на настанот, замислете дека одржувачите на главните компоненти на Linux заминале да работат во Microsoft. Оваа ситуација создава предуслови за користење на Swagger, кој се развива динамично и во најновата - трета верзија - практично се израмнува со RAML во однос на флексибилноста и функционалноста.

Ако не за една работа...

Како што се испоставува, не сите услужни програми со отворен код се ажурирани на OAS 3.0. За микросервисите во Go, најкритично ќе биде недостатокот на адаптација одат-swagging за најновата верзија на стандардот. Сепак, разликата помеѓу 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 и не е поддржан од ниту една од комуналните услуги RAML.

Едно време почнавме да работиме со RAML како пофлексибилен јазик и како резултат на тоа моравме самите да правиме многу работи. На пример, еден од проектите ја користи алатката разгранувања во единица тестови, што поддржува само RAML 0.8. Затоа, моравме да додадеме патерици за да може алатката да ја „јаде“ верзијата RAML 1.0.

Дали треба да изберете?

Откако работевме на комплетирање на екосистемот на решенија за RAML, дојдовме до заклучок дека треба да го претвориме RAML во Swagger 2 и да ја извршиме целата автоматизација, верификација, тестирање и последователна оптимизација во него. Ова е добар начин да се искористи и флексибилноста на RAML и поддршката за алатки за заедницата од Swagger.

За да се реши овој проблем, постојат две OpenSource алатки кои треба да обезбедат конверзија на договор:

1. oas-raml-конвертор е моментално неподдржана алатка. Додека работевме со него, откривме дека има голем број проблеми со сложените RAML кои се „распространети“ на голем број датотеки. Оваа програма е напишана во JavaScript и врши рекурзивна траверзација на синтаксно дрво. Поради динамичното пишување, станува тешко да се разбере овој код, па затоа решивме да не губиме време за пишување закрпи за умирачка алатка.
2. webapi-парсер - алатка од истата компанија која тврди дека е подготвена да конвертира се и сешто, и во која било насока. До денес, најавена е поддршка за RAML 0.8, RAML 1.0 и Swagger 2.0. Меѓутоа, во времето на нашето истражување, полезноста сè уште беше ЕКСТРЕМНО влажна и неупотреблива. Програмерите создаваат еден вид на IR, овозможувајќи им брзо да додаваат нови стандарди во иднина. Но, досега тоа едноставно не функционира.

И тоа не се сите тешкотии на кои наидовме. Еден од чекорите во нашиот гасовод е да потврдиме дека RAML од складиштето е точен во однос на спецификацијата. Пробавме неколку комунални услуги. Изненадувачки, сите тие пцуеја на нашите прибелешки на различни места и со сосема различни лоши зборови. И не секогаш до точка :).

На крајот, се решивме на еден сега веќе застарен проект, кој исто така има голем број проблеми (понекогаш паѓа од ведро небо, има проблеми при работа со регуларни изрази). Така, не најдовме начин да ги решиме проблемите со валидација и конверзија врз основа на бесплатни алатки и решивме да користиме комерцијална алатка. Во иднина, како што алатките на OpenSource стануваат позрели, овој проблем може да стане полесен за решавање. Во меѓувреме, трошоците за работа и време за „довршување“ ни изгледаа позначајни од трошоците за комерцијална услуга.

Заклучок

По сето ова, сакавме да го споделиме нашето искуство и да забележиме дека пред да изберете алатка за опишување договори, треба јасно да дефинирате што сакате од неа и каков буџет сте спремни да инвестирате. Ако заборавиме на OpenSource, веќе има голем број на услуги и производи кои ќе ви помогнат да проверите, конвертирате и потврдите. Но, тие се скапи, а понекогаш и многу скапи. За голема компанија ваквите трошоци се толерантни, но за стартап можат да станат голем товар.

Одредете го збирот на алатки што ќе ги користите подоцна. На пример, ако само треба да прикажете договор, полесно ќе го користите Swagger 2, кој има прекрасен API, бидејќи во RAML ќе треба сами да ја изградите и одржувате услугата.
Колку повеќе задачи имате, толку поголема ќе биде потребата за алатки, а тие се различни за различни платформи и подобро е веднаш да се запознаете со достапните верзии за да направите избор што ќе ги минимизира вашите трошоци во иднина.

Но, вреди да се признае дека сите екосистеми што постојат денес се несовршени. Затоа, ако има обожаватели во компанијата кои сакаат да работат во RAML затоа што „ви овозможува пофлексибилно да ги изразувате мислите“ или, напротив, претпочитаат Swagger затоа што „тоа е појасно“, најдобро е да ги оставите да работат. во она што се Тие се навикнати на тоа и го сакаат тоа, бидејќи алатките на кој било од форматите бараат модификација со датотека.

Што се однесува до нашето искуство, во следните објави ќе зборуваме за тоа какви статички и динамички проверки спроведуваме врз основа на нашата архитектура RAML-Swagger, како и каква документација генерираме од договорите и како сето тоа функционира.

Само регистрирани корисници можат да учествуваат во анкетата. Најави се, вие сте добредојдени.

Кој јазик го користите за да ги прибележите договорите за микроуслуги?

• RAML 0.8

• RAML 1.0

• Свигер 2

• OAS3 (ака)

• Планот

• Останати

• Не се користи

Гласаа 100 корисници. 24 корисници се воздржаа.

Извор: www.habr.com