{"id":38022,"date":"2019-10-31T22:21:14","date_gmt":"2019-10-31T19:21:14","guid":{"rendered":"https:\/\/prohoster.info\/blog\/tak-vse-taki-raml-ili-oas-swagger\/"},"modified":"2019-10-31T22:21:14","modified_gmt":"2019-10-31T19:21:14","slug":"tak-vse-taki-raml-ili-oas-swagger","status":"publish","type":"post","link":"https:\/\/prohoster.info\/sv\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"S\u00e5 vad \u00e4r det? RAML eller OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

I en dynamisk v\u00e4rld av mikrotj\u00e4nster kan allt f\u00f6r\u00e4ndras \u2013 vilken som helst komponent kan skrivas om p\u00e5 ett annat spr\u00e5k, med andra ramverk och arkitektur. Endast kontrakten b\u00f6r f\u00f6rbli of\u00f6r\u00e4ndrade s\u00e5 att man kan interagera med mikrotj\u00e4nsten externt p\u00e5 en viss konstant grund, oavsett interna metamorfoser. Idag kommer vi att ber\u00e4tta om v\u00e5rt problem med att v\u00e4lja formatet f\u00f6r att beskriva kontrakt och dela med oss av de artefakter vi har funnit. <\/p>\n

\"S\u00e5
\n<\/a><\/noindex>
\nInl\u00e4gget \u00e4r f\u00f6rfattat av Anna Melekhova<\/a><\/noindex> och Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikrotj\u00e4nster.<\/b> Vid utvecklingen av Acronis Cyber Cloud ins\u00e5g vi att vi inte kan undkomma dem. Utformningen av en mikrotj\u00e4nst \u00e4r om\u00f6jlig utan formaliserandet av kontraktet, som utg\u00f6r gr\u00e4nssnittet f\u00f6r mikrotj\u00e4nsten.<\/p>\n

Men n\u00e4r produkten inneh\u00e5ller mer \u00e4n en komponent, och utvecklingen av kontraktet blir en regelbunden aktivitet, b\u00f6rjar man oavsiktligt t\u00e4nka p\u00e5 att optimera processen. Det blir uppenbart att gr\u00e4nssnittet (kontraktet) och implementationen (mikrotj\u00e4nsten) m\u00e5ste motsvara varandra, att olika komponenter m\u00e5ste utf\u00f6ra samma uppgifter p\u00e5 ett enhetligt s\u00e4tt, och att utan centraliserad beslutsfattande kommer varje team att tvingas spendera tid p\u00e5 att \u00e5terigen skaffa dessa beslut. <\/p>\n

\"S\u00e5
\nMikrotj\u00e4nstschemat fr\u00e5n Amazon i en tweet<\/a><\/noindex> av Werner Vogels, CTO Amazon<\/i>
\nVad best\u00e5r dilemmat av? De facto finns det tv\u00e5 s\u00e4tt f\u00f6r mikrotj\u00e4nster att interagera \u2013 HTTP Rest och gRPC fr\u00e5n Google. Utan att vilja involveras i Googles teknikstack valde vi HTTP Rest. Annotations f\u00f6r HTTP REST-kontrakten beskrivs oftast i ett av tv\u00e5 format: RAML och OAS, tidigare k\u00e4nt som Swagger. D\u00e4rf\u00f6r st\u00e4lls varje utvecklingsteam inf\u00f6r behovet av att v\u00e4lja ett av standarderna. Men som det visat sig kan detta val vara mycket sv\u00e5rt.<\/p>\n

Varf\u00f6r beh\u00f6vs annotationer?<\/h3>\n

\nEn sammanfattning beh\u00f6vs s\u00e5 att externa anv\u00e4ndare enkelt kan f\u00f6rst\u00e5 vad som kan g\u00f6ras med din tj\u00e4nst via dess HTTP-gr\u00e4nssnitt. Det inneb\u00e4r att en grundl\u00e4ggande sammanfattning minst ska inneh\u00e5lla en lista \u00f6ver tillg\u00e4ngliga resurser, deras HTTP-metoder, f\u00f6rfr\u00e5gans kropp, en uppr\u00e4kning av parametrar, angivande av n\u00f6dv\u00e4ndiga och st\u00f6dda rubriker samt returkoder och svarformat. En extremt viktig del av kontraktsbeskrivningen \u00e4r deras verbala beskrivning (\"vad h\u00e4nder om du l\u00e4gger till denna query-parameter i f\u00f6rfr\u00e5gan?\", \"under vilka omst\u00e4ndigheter returneras kod 400?\")<\/p>\n

Trots detta, n\u00e4r det g\u00e4ller att utveckla ett stort antal mikrotj\u00e4nster, vill man dra nytta av de skrivna sammanfattningarna. Till exempel kan man generera s\u00e5v\u00e4l klient- som serverkod baserat p\u00e5 RAML\/Swagger p\u00e5 en m\u00e4ngd olika programmeringsspr\u00e5k. Dessutom kan man automatiskt f\u00e5 dokumentation f\u00f6r mikrotj\u00e4nsten och ladda upp den p\u00e5 din utvecklarportal :).<\/p>\n

\"S\u00e5
\nExempel p\u00e5 strukturerad kontraktsbeskrivning<\/i><\/p>\n

Det \u00e4r s\u00e4llan man testar mikrotj\u00e4nster baserat p\u00e5 kontraktsbeskrivningar. Om du har skrivit b\u00e5de sammanfattningen och komponenten kan du skapa ett automatiskt test som kontrollerar tj\u00e4nstens korrekthet med olika typer av indata. Returnerar inte tj\u00e4nsten en svarkod som inte beskrivs i sammanfattningen? Kan den korrekt hantera uppenbart felaktiga data?<\/p>\n

Mer \u00e4n s\u00e5, en kvalitativ implementering av inte bara kontrakten utan \u00e4ven verktygen f\u00f6r att visualisera sammanfattningar f\u00f6renklar arbetet med mikrotj\u00e4nsten. Det vill s\u00e4ga, om arkitekten har beskrivit kontraktet kvalitativt, kommer designers och utvecklare att implementera tj\u00e4nsten i andra produkter utan ytterligare tidskostnader.<\/p>\n

F\u00f6r att arbeta med ytterligare verktyg har b\u00e5de RAML och OAS m\u00f6jligheten att l\u00e4gga till metadatan som inte f\u00f6reskrivs av standarden (till exempel, s\u00e5 h\u00e4r g\u00f6rs det i OAS<\/a><\/noindex>).<\/p>\n

I allm\u00e4nhet finns det enormt med utrymme f\u00f6r kreativitet n\u00e4r det g\u00e4ller till\u00e4mpningen av kontrakt f\u00f6r mikrotj\u00e4nster\u2026 \u00e5tminstone teoretiskt<\/p>\n

J\u00e4mf\u00f6relse av igelkott med snok<\/h3>\n

\nF\u00f6r n\u00e4rvarande \u00e4r det prioriterade utvecklingsomr\u00e5det inom Acronis Acronis Cyber Platform. Acronis Cyber Platform \u00e4r nya integrationspunkter f\u00f6r tredjepartstj\u00e4nster med Acronis Cyber Cloud och agentdelen. Trots att v\u00e5ra interna API:er, beskrivna i RAML, har varit tillfredsst\u00e4llande, har behovet av att publicera API \u00e5terigen v\u00e4ckt fr\u00e5gan om vilket annotationsstandard som \u00e4r b\u00e4st att anv\u00e4nda f\u00f6r v\u00e5rt arbete?<\/p>\n

Till en b\u00f6rjan verkade det som att det fanns tv\u00e5 l\u00f6sningar \u2014 de mest spridda bilderna RAML och Swagger (eller OAS). Men det visade sig att det finns minst tre eller fler alternativ.<\/p>\n

\u00c5 ena sidan finns RAML \u2013 ett kraftfullt och effektivt spr\u00e5k. Det implementerar hierarkier och arv v\u00e4l, s\u00e5 detta format passar b\u00e4ttre f\u00f6r stora f\u00f6retag som beh\u00f6ver m\u00e5nga beskrivningar \u2014 det handlar om m\u00e5nga mikrotj\u00e4nster som har gemensamma delar av kontrakt \u2014 autentisering scheman, identiska datatyper, felmeddelanden.<\/p>\n

Men utvecklaren av RAML, f\u00f6retaget Mulesoft, har g\u00e5tt med i Open API-konsortiet som sysslar med utvecklingen Swagger<\/a><\/noindex>. D\u00e4rf\u00f6r har utvecklingen av RAML avstannat. F\u00f6r att f\u00f6rest\u00e4lla sig formatet f\u00f6r h\u00e4ndelser, f\u00f6rest\u00e4ll dig att de som uppr\u00e4tth\u00e5ller de grundl\u00e4ggande komponenterna i Linux har g\u00e5tt f\u00f6r att arbeta p\u00e5 Microsoft. En s\u00e5dan situation skapar f\u00f6ruts\u00e4ttningar f\u00f6r att anv\u00e4nda Swagger, som utvecklas dynamiskt och i den senaste \u2014 tredje versionen \u2014 n\u00e4stan hinner ikapp RAML i flexibilitet och funktionalitet.<\/p>\n

Om det inte vore f\u00f6r en sak...<\/h3>\n

\nDet visade sig att l\u00e5ngt ifr\u00e5n alla open-source verktyg har uppdaterats till OAS 3.0-versionen. F\u00f6r mikrotj\u00e4nster p\u00e5 Go kommer den st\u00f6rsta kritiska punkten att vara avsaknaden av anpassning go-swagger<\/a><\/noindex> till den senaste versionen av standarden. Men skillnaden mellan Swagger 2 och Swagger 3 \u2014 \u00e4r enorm<\/a><\/noindex>. Till exempel har utvecklarna i den tredje versionen:<\/p>\n