{"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\/nl\/blog\/administrirovanie\/tak-vse-taki-raml-ili-oas-swagger","title":{"rendered":"Dus, is het RAML of OAS (Swagger)?","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

In de dynamische wereld van microservices kan alles veranderen \u2014 elke component kan in een andere taal worden herschreven, met andere frameworks en architecturen. Alleen de contracten moeten ongewijzigd blijven, zodat er op een consistente basis met de microservice van buitenaf kan worden samengewerkt, ongeacht interne metamorfosen. Vandaag zullen we onze probleem met de keuze van het formaat voor het beschrijven van contracten bespreken en de gevonden artefacten delen. <\/p>\n

\"Dus,
\n<\/a><\/noindex>
\nDit artikel is voorbereid door Anna Melekhova<\/a><\/noindex> en Vladimir Lapatin<\/a><\/noindex> <\/p>\n

Microservices.<\/b> Bij de ontwikkeling van Acronis Cyber Cloud realiseerden we ons dat we niet om ze heen konden. Ontwerp van een microservice is onmogelijk zonder de formalisering van het contract, dat de interface van de microservice vertegenwoordigt.<\/p>\n

Maar wanneer er meer dan \u00e9\u00e9n component in het product zit en de ontwikkeling van contracten een reguliere activiteit wordt, ga je automatisch nadenken over procesoptimalisatie. Het wordt duidelijk dat de interface (contract) en de implementatie (microservice) elkaar moeten overeenkomen, dat verschillende componenten hetzelfde moeten doen op een uniforme manier, en dat zonder gecentraliseerde besluitvorming over al deze punten elk team steeds weer tijd zal moeten besteden aan het verkrijgen ervan. <\/p>\n

\"Dus,
\nSchema van microservices van Amazon uit een tweet<\/a><\/noindex> van Werner Vogels, CTO van Amazon<\/i>
\nWaaruit bestaat de dilemma? De facto zijn er twee manieren waarop microservices met elkaar communiceren \u2013 HTTP Rest en gRPC van Google. We willen niet betrokken raken bij de technologie\u00ebn van Google, daarom hebben we voor HTTP Rest gekozen. Annotaties voor HTTP REST-contracten worden meestal beschreven in een van de twee formaten: RAML en OAS, voorheen bekend als Swagger. Daarom heeft elk ontwikkelteam de noodzaak om een keuze te maken voor een van de standaard. Maar zoals bleek, kan het maken van deze keuze erg ingewikkeld zijn.<\/p>\n

Waarom zijn annotaties nodig?<\/h3>\n

\nEen annotatie is nodig zodat externe gebruikers snel kunnen begrijpen wat ze met uw service kunnen doen via de HTTP-interface. Op basisniveau moet de annotatie ten minste een lijst van beschikbare bronnen bevatten, hun HTTP-methoden, verzoeklichamen, een opsomming van parameters, de vereiste en ondersteunde headers, evenals retourcodes en responformaten. Een uiterst belangrijk element van de contractannotatie is hun verbale beschrijving (\u201cwat gebeurt er als ik deze queryparameter aan het verzoek toevoeg?\u201d, \u201cin welk geval wordt retourcode 400 gegeven?\u201d)<\/p>\n

Echter, wanneer het gaat om de ontwikkeling van een groot aantal microservices, wil je extra voordeel halen uit de geschreven annotaties. Op basis van RAML\/Swagger kan zowel client- als servercode gegenereerd worden in een groot aantal programmeertalen. Bovendien kan je automatisch documentatie voor de microservice verkrijgen en deze uploaden naar uw developer-portal :).<\/p>\n

\"Dus,
\nVoorbeeld van een gestructureerde contractbeschrijving<\/i><\/p>\n

Het komt minder vaak voor dat microservices getest worden op basis van contractbeschrijvingen. Als u zowel de annotatie als de component hebt geschreven, kunt u een autotest maken die verifieert of de service adequaat werkt met verschillende ingangsdatatypes. Geeft de service geen retourcode terug die niet in de annotatie is beschreven? Kan het onjuiste gegevens correct verwerken?<\/p>\n

Bovendien maakt een kwalitatieve implementatie van niet alleen de contracten, maar ook de tools voor het visualiseren van annotaties het werken met de microservice eenvoudiger. Dit betekent dat als de architect het contract goed heeft beschreven, ontwerpers en ontwikkelaars de service in andere producten kunnen integreren zonder extra tijdsverlies.<\/p>\n

Voor de werking van extra tools hebben zowel RAML als OAS de mogelijkheid om metadata toe te voegen die niet door de standaard worden voorzien (bijvoorbeeld, zo wordt dit gedaan in OAS<\/a><\/noindex>).<\/p>\n

Over het algemeen is het veld voor creativiteit in de toepassing van contracten voor microservices enorm... tenminste theoretisch<\/p>\n

Vergelijking van een eg met een adder<\/h3>\n

\nMomenteel is de prioriteit van ontwikkeling bij Acronis de ontwikkeling van het Acronis Cyber Platform. Acronis Cyber Platform zijn nieuwe integratiepunten voor externe diensten met Acronis Cyber Cloud en de agentensectie. Hoewel onze interne API's, beschreven in RAML, ons bevielen, heeft de noodzaak om de API te publiceren weer de vraag opgeworpen: welke standaard voor annotaties kunnen we het beste gebruiken voor ons werk?<\/p>\n

In het begin leek het erop dat er twee oplossingen waren - de meest voorkomende ontwikkelingen RAML en Swagger (of OAS). Maar in werkelijkheid blijken er minstens drie of meer alternatieven te zijn.<\/p>\n

Aan de ene kant is er RAML - een krachtige en effici\u00ebnte taal. Het heeft een goede hi\u00ebrarchie en erfelijkheid, zodat dit formaat beter geschikt is voor grote bedrijven die veel beschrijvingen nodig hebben - dat wil zeggen niet \u00e9\u00e9n product, maar veel microservices die gemeenschappelijke contractonderdelen hebben - authenticatieschema's, dezelfde datatypes, foutlichamen.<\/p>\n

Maar de ontwikkelaar van RAML, het bedrijf Mulesoft, heeft zich aangesloten bij het Open API-consortium, dat zich bezighoudt met de ontwikkeling Swagger<\/a><\/noindex>. Daarom is de ontwikkeling van RAML stilgelegd. Stel je voor dat de maintainers van de belangrijkste Linux-componenten bij Microsoft zijn gaan werken. Zo'n situatie cre\u00ebert voorwaarden om Swagger te gebruiken, dat dynamisch evolueert en in de laatste - derde versie - bijna RAML inhaalt qua flexibiliteit en functionaliteit.<\/p>\n

Als het niet voor \u00e9\u00e9n maar was...<\/h3>\n

\nZoals bleek, hebben lang niet alle open-source tools zich ge\u00fcpdatet naar versie OAS 3.0. Voor microservices in Go is het ontbreken van aanpassing go-swagger<\/a><\/noindex> voor de nieuwe standaard zijn het grootste probleem. Echter, het verschil tussen Swagger 2 en Swagger 3 is - enorm<\/a><\/noindex>. Bijvoorbeeld, in de derde versie hebben ontwikkelaars:<\/p>\n