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

In der dynamischen Welt der Mikrodienste kann sich alles \u00e4ndern \u2013 jede Komponente kann in einer anderen Sprache neu geschrieben werden, unter Verwendung anderer Frameworks und Architekturen. Nur die Vertr\u00e4ge sollten unver\u00e4nderlich bleiben, damit der Mikrodienst von au\u00dfen auf einer konstanten Grundlage interagiert werden kann, unabh\u00e4ngig von den internen Metamorphosen. Heute werden wir \u00fcber unser Problem bei der Wahl des Formats zur Beschreibung von Vertr\u00e4gen berichten und die gefundenen Artefakte teilen. <\/p>\n

\"Also,
\n<\/a><\/noindex>
\nBeitrag verfasst von Anna Melekhova<\/a><\/noindex> und Wladimir Lapatin<\/a><\/noindex> <\/p>\n

Mikrodienste.<\/b> Bei der Entwicklung von Acronis Cyber Cloud wurde uns klar, dass wir nicht um sie herumkommen. Das Design eines Mikrodienstes ist ohne die Formalisierung des Vertrags, der die Schnittstelle des Mikrodienstes darstellt, nicht m\u00f6glich.<\/p>\n

Wenn ein Produkt mehr als eine Komponente enth\u00e4lt und die Vertragsentwicklung zu einer regelm\u00e4\u00dfigen Aktivit\u00e4t wird, beginnt man unweigerlich \u00fcber eine Optimierung des Prozesses nachzudenken. Es wird offensichtlich, dass das Interface (Vertrag) und die Implementierung (Mikroservice) aufeinander abgestimmt sein m\u00fcssen, dass verschiedene Komponenten dieselben Aufgaben auf die gleiche Weise erledigen sollten und dass ohne eine zentralisierte Entscheidungsfindung jede Mannschaft immer wieder Zeit investieren muss, um diese zu erhalten. <\/p>\n

\"Also,
\nDas Schema der Mikroservices von Amazon aus einem Tweet<\/a><\/noindex> von Werner Vogels, CTO von Amazon<\/i>
\nWas ist das Dilemma? De facto gibt es zwei M\u00f6glichkeiten f\u00fcr die Interaktion von Mikroservices \u2013 HTTP Rest und gRPC von Google. Um nicht in das Technologie-Stack von Google involviert zu werden, haben wir uns f\u00fcr HTTP Rest entschieden. Die Annotations zu HTTP REST-Vertr\u00e4gen werden meist in einem der beiden Formate beschrieben: RAML und OAS, fr\u00fcher bekannt als Swagger. Deshalb steht jedes Entwicklerteam vor der Notwendigkeit, sich f\u00fcr einen der Standards zu entscheiden. Doch, wie sich herausstellte, kann diese Entscheidung sehr kompliziert sein.<\/p>\n

Warum sind Annotations notwendig?<\/h3>\n

\nEine Annotation ist erforderlich, damit externe Benutzer leicht verstehen, was sie \u00fcber die HTTP-Schnittstelle Ihres Dienstes tun k\u00f6nnen. Auf einer grundlegenden Ebene sollte die Annotation mindestens eine Liste der verf\u00fcgbaren Ressourcen, deren HTTP-Methoden, Anfragek\u00f6rper, Parameter, notwendige und unterst\u00fctzte Header sowie R\u00fcckgabecodes und Antwortformate enthalten. Ein \u00e4u\u00dferst wichtiger Bestandteil der Vertragsannotation ist auch deren verbale Beschreibung (\"Was passiert, wenn ich diesen Query-Parameter zur Anfrage hinzuf\u00fcge?\", \"In welchem Fall wird der Code 400 zur\u00fcckgegeben?\").<\/p>\n

Dennoch, wenn es um die Entwicklung einer gro\u00dfen Anzahl von Mikrodiensten geht, m\u00f6chte man zus\u00e4tzlichen Nutzen aus den geschriebenen Annotationen ziehen. Beispielsweise k\u00f6nnen auf Basis von RAML\/Swagger sowohl Client- als auch Serverseitencodes in einer Vielzahl von Programmiersprachen generiert werden. Au\u00dferdem kann automatisch Dokumentation zu dem Mikrodienst erstellt und auf Ihr Entwickler-Portal hochgeladen werden :).<\/p>\n

\"Also,
\nBeispiel f\u00fcr eine strukturierte Beschreibung eines Vertrags<\/i><\/p>\n

Es ist weniger verbreitet, dass Mikrodienste basierend auf Vertragsbeschreibungen getestet werden. Wenn Sie sowohl die Annotation als auch die Komponente geschrieben haben, k\u00f6nnen Sie einen automatisierten Test erstellen, der die Angemessenheit der Funktionsweise des Dienstes mit verschiedenen Eingabedatentypen \u00fcberpr\u00fcft. Gibt der Dienst einen Antwortcode zur\u00fcck, der nicht in der Annotation beschrieben ist? Kann er ung\u00fcltige Daten korrekt verarbeiten?<\/p>\n

Dar\u00fcber hinaus erm\u00f6glicht eine qualitativ hochwertige Umsetzung nicht nur der Vertr\u00e4ge selbst, sondern auch der Werkzeuge zur Visualisierung von Annotationen eine Vereinfachung der Arbeit mit dem Mikrodienst. Wenn der Architekt den Vertrag gut beschrieben hat, k\u00f6nnen Designer und Entwickler basierend darauf den Dienst in andere Produkte einf\u00fchren, ohne zus\u00e4tzliche Zeitaufwendungen.<\/p>\n

F\u00fcr die Funktion zus\u00e4tzlicher Werkzeuge haben sowohl RAML als auch OAS die M\u00f6glichkeit, Metadaten hinzuzuf\u00fcgen, die im Standard nicht vorgesehen sind (zum Beispiel, so wird das in OAS gemacht<\/a><\/noindex>).<\/p>\n

Im Allgemeinen gibt es im kreativen Einsatz von Vertr\u00e4gen f\u00fcr Mikrodienste ein riesiges Potenzial... zumindest theoretisch<\/p>\n

Der Vergleich eines Igels mit einer Natter<\/h3>\n

\nDerzeit liegt der Schwerpunkt der Entwicklung bei Acronis auf der Acronis Cyber Platform. Die Acronis Cyber Platform bietet neue Integrationspunkte f\u00fcr externe Dienste mit der Acronis Cyber Cloud und dem Agententeil. Obwohl unsere internen APIs, die in RAML beschrieben sind, zufriedenstellend waren, hat die Notwendigkeit der Ver\u00f6ffentlichung von APIs erneut die Frage aufgeworfen, welcher Annotationsstandard f\u00fcr unsere Arbeit am besten geeignet ist.<\/p>\n

Anfangs schien es, als g\u00e4be es zwei L\u00f6sungen \u2013 die am h\u00e4ufigsten verwendeten Entwicklungen RAML und Swagger (oder OAS). Tats\u00e4chlich stellte sich jedoch heraus, dass es mindestens drei oder mehr Alternativen gibt.<\/p>\n

Auf der einen Seite gibt es RAML \u2013 eine m\u00e4chtige und effiziente Sprache. Sie bietet eine gut umgesetzte Hierarchie und Vererbung, wodurch dieses Format besser f\u00fcr gro\u00dfe Unternehmen geeignet ist, die viele Beschreibungen ben\u00f6tigen \u2013 das hei\u00dft, nicht nur ein Produkt, sondern zahlreiche Mikrodienste, die gemeinsame Teile von Vertr\u00e4gen aufweisen \u2013 Authentifizierungsschemata, identische Datentypen, Fehlermeldungen.<\/p>\n

Der Entwickler von RAML, das Unternehmen Mulesoft, hat sich dem Open API-Konsortium angeschlossen, das sich der Weiterentwicklung widmet. Swagger<\/a><\/noindex>. Daher hat RAML seine Entwicklung eingestellt. Um sich das Ereignisformat vorzustellen, kann man sich vorstellen, dass die Entwickler der Hauptkomponenten von Linux zu Microsoft gewechselt sind. Eine solche Situation f\u00fchrt dazu, dass Swagger, das sich dynamisch weiterentwickelt, in der neuesten \u2013 dritten Version \u2013 RAML in Bezug auf Flexibilit\u00e4t und Funktionalit\u00e4t fast einholt.<\/p>\n

W\u00e4re da nicht eine Kleinigkeit\u2026<\/h3>\n

\nWie sich herausgestellt hat, haben lange nicht alle Open-Source-Tools auf die Version OAS 3.0 aktualisiert. F\u00fcr Microservices in Go ist das Fehlen einer Anpassung hierf\u00fcr besonders kritisch. go-swagger<\/a><\/noindex> auf die neue Version des Standards. Der Unterschied zwischen Swagger 2 und Swagger 3 ist jedoch \u2013 enorm<\/a><\/noindex>. Zum Beispiel haben die Entwickler in der dritten Version:<\/p>\n