🥇Så hvad er valget: RAML eller OAS (Swagger)?

I en dynamisk verden af mikrotjenester kan alt ændre sig — enhver komponent kan genskrives i et andet sprog ved hjælp af forskellige rammer og arkitektur. Kun kontrakterne skal forblive uændrede, så mikrotjenesten kan interagere eksternt på en stabil basis uanset de interne transformationer. I dag vil vi fortælle om vores problem med at vælge formatet til beskrivelse af kontrakter og dele de artefakter, vi har fundet.

Indlægget er forberedt af Anna Melekhova og Vladimir Lapatin

Mikrotjenester. Ved udviklingen af Acronis Cyber Cloud indså vi, at vi ikke kunne undgå dem. Og designet af en mikrotjeneste er umuligt uden at formalisere kontrakten, som repræsenterer mikrotjenestens interface.

Men når produktet indeholder mere end én komponent, og udviklingen af kontrakten bliver en regelmæssig aktivitet, begynder man uundgåeligt at tænke over optimering af processen. Det bliver klart, at interface (kontrakt) og implementering (mikrotjeneste) skal matche hinanden, at forskellige komponenter skal udføre de samme opgaver på samme måde, og at uden en centraliseret beslutningsproces vil hvert team være nødt til at bruge tid på at opnå dem igen og igen.

Skema for mikrotjenester fra Amazon fra tweeten af Werner Vogels, CTO Amazon
Hvad er dilemmaet? De facto er der to måder, hvorpå mikrotjenester kan interagere – HTTP Rest og gRPC fra Google. Uden at ønske at blive involveret i Googles teknologistak, valgte vi HTTP Rest. Annotationer til HTTP REST-kontrakter beskrives oftest i et af to formater: RAML og OAS, tidligere kendt som Swagger. Derfor står hvert udviklerteam over for valget af én standard. Men som det viste sig, kan det være meget svært at træffe dette valg.

Hvorfor er annotationer nødvendige?

En annotation er nødvendig, så eksterne brugere nemt kan forstå, hvad de kan gøre med din service gennem dens HTTP-interface. På et grundlæggende niveau skal annotationen indeholde mindst en liste over tilgængelige ressourcer, deres HTTP-metoder, anmodningernes krop, opregning af parametre, angivelse af nødvendige og understøttede overskrifter samt statuskoder og svarformater. Et ekstremt vigtigt element i kontraktannotation er også deres beskrivende forklaring ("hvad sker der, hvis man tilføjer denne query-parameter til anmodningen?", "hvornår bliver statuskode 400 returneret?")

Når der er tale om udvikling af et stort antal mikrotjenester, er det dog ønskeligt at udvinde ekstra værdi fra de skrevne annotationer. For eksempel kan man baseret på RAML/Swagger generere både klient- og serverkode på et enormt antal programmeringssprog. Man kan også automatisk generere dokumentation til mikrotjenesten og uploade den til din udviklerportal :).

Eksempel på struktureret kontraktbeskrivelse

Det er sjældnere at se praksis med at teste mikrotjenester baseret på kontraktbeskrivelser. Hvis du har skrevet både annotationen og komponenten, kan du oprette en automatisk test, der kontrollerer, om servicen fungerer korrekt med forskellige typer data som input. Returnerer servicen en svarkode, der ikke er beskrevet i annotationen? Kan den håndtere forskriftsmæssigt forkerte data korrekt?

Desuden gør en kvalitetsimplementering af både kontrakterne og værktøjer til visualisering af annotationer arbejdet med mikrotjenesten lettere. Det vil sige, hvis arkitekten har beskrevet kontrakten grundigt, vil designere og udviklere kunne integrere servicen i andre produkter uden yderligere tidsomkostninger.

For brug af yderligere værktøjer kan både RAML og OAS tilføje metadata, som ikke er omfattet af standarden (for eksempel hvordan dette gøres i OAS).

Generelt er der et enormt kreativt rum i anvendelsen af kontrakter til mikrotjenester... i det mindste teoretisk

Sammenligning af en igle med en snog

I øjeblikket er Acronis' prioriterede udviklingsretning Acronis Cyber Platform. Acronis Cyber Platform er de nye integrationspunkter for tredjepartstjenester med Acronis Cyber Cloud og agentdelen. Selvom vores interne API'er, beskrevet i RAML, var tilstrækkelige, rejste behovet for at offentliggøre API'et igen spørgsmålet om, hvilken standard for annoteringer der er bedst at bruge til vores arbejde?

Oprindeligt så det ud til, at der var to løsninger — de mest udbredte udviklinger RAML og Swagger (eller OAS). Men i praksis viste det sig, at der er mindst tre, hvis ikke flere alternativer.

På den ene side er der RAML — et kraftfuldt og effektivt sprog. Det har en god implementering af hierarki og arv, så dette format passer bedre til store virksomheder, der har brug for mange beskrivelser — det vil sige ikke ét produkt, men mange mikrotjenester, som har fælles elementer i deres kontrakter — autentificeringsskemaer, ens datatyper, fejlmeddelelser.

Men udvikleren af RAML, Mulesoft, har tilsluttet sig konsortiet Open API, som arbejder på udviklingen af Swagger. Derfor er udviklingen af RAML blevet sat på pause. For at forestille sig formatet af begivenheden, kan man tænke på, at vedligeholderne af de primære komponenter i Linux gik over til Microsoft. En sådan situation skaber forudsætninger for at bruge Swagger, som udvikler sig dynamisk, og i den seneste — tredje version — næsten indhenter RAML når det kommer til fleksibilitet og funktionalitet.

Hvis det ikke var for én ting…

Det viste sig, at langt fra alle open-source værktøjer var opdateret til OAS 3.0-versionen. For mikrotjenester skrevet i Go vil det kritiske være fraværet af tilpasning go-swagger til den nye version af standarden. Men forskellen mellem Swagger 2 og Swagger 3 er enorm. For eksempel har udviklerne i den tredje version:

forbedret beskrivelsen af autentificeringsskemaer
færdiggjort understøttelsen af JSON Schema
opgraderet muligheden for at tilføje eksempler

Situationen er derfor sjov: når man vælger standarden, skal man overveje RAML, Swagger 2 og Swagger 3 som separate alternativer. Her har kun Swagger 2 god støtte fra OpenSource-værktøjer. RAML er meget fleksibel… og kompleks, mens Swagger 3 har begrænset support fra fællesskabet, så du må bruge værktøjer, der er udviklet internt eller kommercielle løsninger, som typisk er ret dyre.

Samtidig findes der mange behagelige funktioner i Swagger, såsom en klar portal editor.swagger.io, hvor man kan uploade en annotering og få dens visualisering med en detaljeret beskrivelse, links og relationer, er der ikke mulighed for noget lignende med det mere grundlæggende og mindre brugervenlige RAML. Ja, man kan søge efter noget blandt projekter på GitHub, finde en tilsvarende og selv implementere det. Men uanset hvad, skal nogen vedligeholde portalen, hvilket ikke er så praktisk til grundlæggende brug eller testformål. Derudover er Swagger mere “principløst” eller liberalt - det kan genereres fra kommentarer i koden, hvilket selvfølgelig går imod API-first-princippet og ikke understøttes af noget værktøj til RAML.

Dengang begyndte vi at arbejde med RAML som et mere fleksibelt sprog, og endte med at skulle lave meget selv. For eksempel bruger et af vores projekter et værktøj ramlfications i unit-tests, som kun understøtter RAML 0.8. Så vi måtte tilføje nogen løsninger, så værktøjet kunne “fortære” RAML version 1.0.

Er det nødvendigt at vælge?

Efter at have brugt tid på at tilføje økosystemløsninger til RAML, kom vi frem til, at vi skal konvertere RAML til Swagger 2 og derefter udføre al automatisering, kontrollere, teste og efterfølgende optimere i det. Det er en god måde at udnytte både fleksibiliteten i RAML og støtte fra fællesskabet med Swagger-værktøjer.

Til at løse denne opgave findes der to OpenSource-værktøjer, som skal kunne konvertere kontrakter:

oas-raml-converter – et i øjeblikket ikke-understøttet værktøj. Under arbejdet med det opdagede vi, at det har en række problemer med komplekse RAML'er, der er “spredt” over mange filer. Dette program er skrevet i JavaScript og udfører en rekursiv gennemgang af syntaktisk træ. På grund af den dynamiske typisering blev det svært at forstå koden, så vi besluttede ikke at bruge tid på at skrive patches til det døende værktøj.
webapi-parser — et værktøj fra det samme firma, der hævder at være klar til at konvertere alt mellem himmel og jord, og det i begge retninger. På nuværende tidspunkt er der påstået støtte for RAML 0.8, RAML 1.0 og Swagger 2.0. Men på tidspunktet for vores undersøgelse var værktøjet stadig ULTRA råt og uegnet til brug. Udviklerne skaber en slags IR, hvilket vil gøre det muligt for dem hurtigt at tilføje nye standarder i fremtiden. Men indtil da fungerer alt dette bare ikke.

Og det er endnu ikke alle de problemer, vi har stødt på. Et af trinene i vores pipeline er at kontrollere, at RAML fra depotet er korrekt i forhold til specifikationen. Vi har prøvet flere værktøjer. Utroligt nok brokkede de sig alle over vores annotationer forskellige steder med forskellige klager. Og det var ikke altid berettiget :).

Til sidst endte vi med et nu forældet projekt, som også har en række problemer (det går nogle gange ned uden grund, har problemer med regulære udtryk). Dermed fandt vi ikke en måde at løse validerings- og konverteringsopgaverne baseret på gratis værktøjer, og besluttede at bruge et kommercielt værktøj. I fremtiden, når OpenSource-værktøjer bliver mere udviklede, kan det blive nemmere at løse denne opgave. Indtil videre forekom arbejds- og tidsomkostningerne ved at "fikse" det mere betydelige end prisen på den kommercielle tjeneste.

Konklusion

Efter al dette ønskede vi at dele vores erfaring og bemærke, at når man vælger et værktøj til beskrivelse af kontrakter, skal man være klar over, hvad man ønsker fra det, og hvilket budget man er villig til at investere. Hvis man ser bort fra OpenSource, er der allerede nu mange tjenester og produkter, der kan hjælpe med at lave kontroller, konvertere og validere. Men de er dyre, og nogle gange - meget dyre. For en stor virksomhed er sådanne omkostninger tolerable, men for en opstartsvirksomhed kan de udgøre en stor byrde.

Bestem det sæt værktøjer, du vil bruge senere. For eksempel, hvis du blot har brug for at vise en kontrakt, vil det være lettere at bruge Swagger 2, som har et pænt API, da du selv skal oprette og vedligeholde tjenesten i RAML.
Jo flere opgaver du har, desto større bliver behovet for værktøjer, og de er forskellige for forskellige platforme, så det er bedst at sætte sig ind i de tilgængelige versioner for at træffe et valg, der minimerer dine omkostninger i fremtiden.

Men må erkende, at alle de økosystemer, der findes i dag, er ufuldkomne. Så hvis der er entusiaster i virksomheden, der elsker at arbejde med RAML, fordi "det giver mulighed for at udtrykke tankerne mere fleksibelt", eller omvendt foretrækker Swagger, fordi "det er mere forståeligt", så er det bedst at lade dem arbejde i det, de er vant til og ønsker, da værktøjet for begge formater kræver finjustering.

Når det kommer til vores erfaring, vil vi i de følgende indlæg fortælle om, hvilke - statiske og dynamiske kontroller vi udfører baseret på vores RAML-Swagger-arkitektur, samt hvilken dokumentation vi genererer ud fra kontrakterne, og hvordan alt dette fungerer.

Kun registrerede brugere kan deltage i undersøgelsen. Log ind, please.