🥇Så, är det RAML eller OAS (Swagger)?

I en dynamisk värld av mikrotjänster kan allt förändras – vilken som helst komponent kan skrivas om på ett annat språk, med andra ramverk och arkitektur. Endast kontrakten bör förbli oförändrade så att man kan interagera med mikrotjänsten externt på en viss konstant grund, oavsett interna metamorfoser. Idag kommer vi att berätta om vårt problem med att välja formatet för att beskriva kontrakt och dela med oss av de artefakter vi har funnit.

Inlägget är författat av Anna Melekhova och Vladimir Lapatin

Mikrotjänster. Vid utvecklingen av Acronis Cyber Cloud insåg vi att vi inte kan undkomma dem. Utformningen av en mikrotjänst är omöjlig utan formaliserandet av kontraktet, som utgör gränssnittet för mikrotjänsten.

Men när produkten innehåller mer än en komponent, och utvecklingen av kontraktet blir en regelbunden aktivitet, börjar man oavsiktligt tänka på att optimera processen. Det blir uppenbart att gränssnittet (kontraktet) och implementationen (mikrotjänsten) måste motsvara varandra, att olika komponenter måste utföra samma uppgifter på ett enhetligt sätt, och att utan centraliserad beslutsfattande kommer varje team att tvingas spendera tid på att återigen skaffa dessa beslut.

Mikrotjänstschemat från Amazon i en tweet av Werner Vogels, CTO Amazon
Vad består dilemmat av? De facto finns det två sätt för mikrotjänster att interagera – HTTP Rest och gRPC från Google. Utan att vilja involveras i Googles teknikstack valde vi HTTP Rest. Annotations för HTTP REST-kontrakten beskrivs oftast i ett av två format: RAML och OAS, tidigare känt som Swagger. Därför ställs varje utvecklingsteam inför behovet av att välja ett av standarderna. Men som det visat sig kan detta val vara mycket svårt.

Varför behövs annotationer?

En sammanfattning behövs så att externa användare enkelt kan förstå vad som kan göras med din tjänst via dess HTTP-gränssnitt. Det innebär att en grundläggande sammanfattning minst ska innehålla en lista över tillgängliga resurser, deras HTTP-metoder, förfrågans kropp, en uppräkning av parametrar, angivande av nödvändiga och stödda rubriker samt returkoder och svarformat. En extremt viktig del av kontraktsbeskrivningen är deras verbala beskrivning ("vad händer om du lägger till denna query-parameter i förfrågan?", "under vilka omständigheter returneras kod 400?")

Trots detta, när det gäller att utveckla ett stort antal mikrotjänster, vill man dra nytta av de skrivna sammanfattningarna. Till exempel kan man generera såväl klient- som serverkod baserat på RAML/Swagger på en mängd olika programmeringsspråk. Dessutom kan man automatiskt få dokumentation för mikrotjänsten och ladda upp den på din utvecklarportal :).

Exempel på strukturerad kontraktsbeskrivning

Det är sällan man testar mikrotjänster baserat på kontraktsbeskrivningar. Om du har skrivit både sammanfattningen och komponenten kan du skapa ett automatiskt test som kontrollerar tjänstens korrekthet med olika typer av indata. Returnerar inte tjänsten en svarkod som inte beskrivs i sammanfattningen? Kan den korrekt hantera uppenbart felaktiga data?

Mer än så, en kvalitativ implementering av inte bara kontrakten utan även verktygen för att visualisera sammanfattningar förenklar arbetet med mikrotjänsten. Det vill säga, om arkitekten har beskrivit kontraktet kvalitativt, kommer designers och utvecklare att implementera tjänsten i andra produkter utan ytterligare tidskostnader.

För att arbeta med ytterligare verktyg har både RAML och OAS möjligheten att lägga till metadatan som inte föreskrivs av standarden (till exempel, så här görs det i OAS).

I allmänhet finns det enormt med utrymme för kreativitet när det gäller tillämpningen av kontrakt för mikrotjänster… åtminstone teoretiskt

Jämförelse av igelkott med snok

För närvarande är det prioriterade utvecklingsområdet inom Acronis Acronis Cyber Platform. Acronis Cyber Platform är nya integrationspunkter för tredjepartstjänster med Acronis Cyber Cloud och agentdelen. Trots att våra interna API:er, beskrivna i RAML, har varit tillfredsställande, har behovet av att publicera API återigen väckt frågan om vilket annotationsstandard som är bäst att använda för vårt arbete?

Till en början verkade det som att det fanns två lösningar — de mest spridda bilderna RAML och Swagger (eller OAS). Men det visade sig att det finns minst tre eller fler alternativ.

Å ena sidan finns RAML – ett kraftfullt och effektivt språk. Det implementerar hierarkier och arv väl, så detta format passar bättre för stora företag som behöver många beskrivningar — det handlar om många mikrotjänster som har gemensamma delar av kontrakt — autentisering scheman, identiska datatyper, felmeddelanden.

Men utvecklaren av RAML, företaget Mulesoft, har gått med i Open API-konsortiet som sysslar med utvecklingen Swagger. Därför har utvecklingen av RAML avstannat. För att föreställa sig formatet för händelser, föreställ dig att de som upprätthåller de grundläggande komponenterna i Linux har gått för att arbeta på Microsoft. En sådan situation skapar förutsättningar för att använda Swagger, som utvecklas dynamiskt och i den senaste — tredje versionen — nästan hinner ikapp RAML i flexibilitet och funktionalitet.

Om det inte vore för en sak...

Det visade sig att långt ifrån alla open-source verktyg har uppdaterats till OAS 3.0-versionen. För mikrotjänster på Go kommer den största kritiska punkten att vara avsaknaden av anpassning go-swagger till den senaste versionen av standarden. Men skillnaden mellan Swagger 2 och Swagger 3 — är enorm. Till exempel har utvecklarna i den tredje versionen:

förbättrat beskrivningen av autentisering scheman
slutfört stödet för JSON Schema
förbättrat möjligheten att lägga till exempel

Situationen blir lustig: vid valet av standard måste RAML, Swagger 2 och Swagger 3 betraktas som separata alternativ. Endast Swagger 2 har ett bra stöd för OpenSource-verktyg. RAML är mycket flexibelt… och komplicerat, medan Swagger 3 har svagt stöd från gemenskapen, så du kommer att behöva använda egna utvecklade verktyg eller kommersiella lösningar som vanligtvis kostar ganska mycket.

Det finns många trevliga funktioner i Swagger, som en färdig portal editor.swagger.io, som man kan ladda upp en anmälan till och få en visuell presentation med detaljerad beskrivning, länkar och relationer, så finns det inte samma möjlighet för den mer fundamentala och mindre användarvänliga RAML. Ja, man kan söka efter något bland projekten på GitHub, hitta en motsvarighet där och själv ställa in det. I vilket fall måste någon underhålla portalen, vilket inte är så bekvämt för grundläggande användning eller testbehov. Dessutom är swagger mer "principlös", eller liberal - den kan genereras från kommentarer i koden, vilket förstås strider mot principen API first och stöds inte av något av verktygen för RAML.

Vi började vid ett tillfälle arbeta med RAML, eftersom det var ett mer flexibelt språk, och slutade med att vi fick göra mycket själva. Till exempel används ett verktyg i ett av projekten ramlfications i enhetstester som endast stöder RAML 0.8. Så vi var tvungna att lägga till lösningar för att verktyget skulle kunna "äta" RAML version 1.0.

Är det verkligen nödvändigt att välja?

Efter att ha kämpat med att komplettera lösningssystemet för RAML, kom vi fram till att vi behöver konvertera RAML till Swagger 2 och utföra all automatisering, validering, testning och efterföljande optimering där. Det är ett bra sätt att använda både flexibiliteten hos RAML och verktygsstödet från communityn som Swagger erbjuder.

För att lösa denna uppgift finns det två OpenSource-verktyg som ska säkerställa konverteringen av kontrakt:

oas-raml-converter – numera en icke-underhållen verktyg. Under arbetet med det upptäckte vi att det uppstår ett antal problem med komplexa RAML-filer som är "spridda" över ett stort antal filer. Detta program är skrivet i JavaScript och utför en rekursiv genomgång av syntaxträdet. På grund av dynamisk typning blev det svårt att förstå denna kod, så vi beslutade att inte slösa tid på att skriva patchar till ett utdöende verktyg.
webapi-parser — ett verktyg från samma företag som påstår sig kunna konvertera allt och alla, i vilken riktning som helst. I dagsläget deklareras stöd för RAML 0.8, RAML 1.0 och Swagger 2.0. Men vid tidpunkten för vår undersökning var verktyget fortfarande EXTREMT rått och olämpligt för användning. Utvecklarna skapar en sorts IR, vilket kommer att göra det möjligt för dem att snabbt lägga till nya standarder i framtiden. Men för tillfället fungerar allt detta helt enkelt inte.

Och det är inte allt besvär vi har stått inför. Ett av stegen i vår pipeline är att kontrollera att RAML från förrådet är korrekt i förhållande till specifikationen. Vi har provat flera verktyg. Förvånande nog klagade alla på våra anteckningar på olika ställen med helt olika dumma ord. Ofta utan att ha någon poäng :).

Till slut bestämde vi oss för ett numera föråldrat projekt, som också har en rad problem (den kraschar ibland utan anledning, har problem med regex). Därmed hittade vi inget sätt att lösa validering och konvertering med hjälp av gratisverktyg, och beslutade att använda ett kommersiellt verktyg. I framtiden, när OpenSource-verktyg blir mer avancerade, kan det här problemet kanske bli enklare. Men för tillfället verkar arbets- och tidskostnaderna för att "förbättra" vara mer betydande än kostnaden för den kommersiella tjänsten.

Slutsats

Efter allt detta ville vi dela med oss av vår erfarenhet och påpeka att innan man väljer ett verktyg för att beskriva kontrakt, behöver man tydligt definiera vad man vill ha ut av det och vilken budget man är beredd att investera. Om man bortser från OpenSource, finns det redan många tjänster och produkter som kan hjälpa till med kontroll, konvertering och validering. Men de är dyra, ibland mycket dyra. För stora företag är sådana kostnader acceptabla, men för startups kan de bli en stor belastning.

Definiera de verktyg du kommer att använda senare. Till exempel, om du bara behöver visa kontrakt, är det enklare att använda Swagger 2, som har ett snyggt API, eftersom du själv måste driva och underhålla tjänsten för RAML.
Ju fler uppgifter du har, desto större blir behovet av verktyg, och de är olika för olika plattformar. Det är bättre att bekanta sig med tillgängliga versioner direkt för att göra ett val som minimerar dina framtida kostnader.

Men det måste erkännas att alla ekosystem som finns idag är ofullkomliga. Så om det finns fans inom företaget som älskar att arbeta i RAML eftersom "det tillåter en mer flexibel uttrycksförmåga", eller tvärtom föredrar Swagger eftersom "det är mer begripligt", är det bäst att låta dem arbeta i det de är vana vid och vill, eftersom verktygen för vilket av formaten som helst kräver finslipning.

När det gäller vår erfarenhet kommer vi i följande inlägg att berätta om vilka statiska och dynamiska kontroller vi genomför baserat på vår RAML-Swagger-arkitektur, samt vilken dokumentation vi genererar från kontrakten och hur allt detta fungerar.

Endast registrerade användare kan delta i omröstningen. Logga in, tack.