🥇 RAML oder OAS (Swagger)?

In der dynamischen Welt der Mikrodienste kann sich alles ändern – jede Komponente kann in einer anderen Sprache neu geschrieben werden, unter Verwendung anderer Frameworks und Architekturen. Nur die Verträge sollten unveränderlich bleiben, damit der Mikrodienst von außen auf einer konstanten Grundlage interagiert werden kann, unabhängig von den internen Metamorphosen. Heute werden wir über unser Problem bei der Wahl des Formats zur Beschreibung von Verträgen berichten und die gefundenen Artefakte teilen.

Beitrag verfasst von Anna Melekhova und Wladimir Lapatin

Mikrodienste. 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öglich.

Wenn ein Produkt mehr als eine Komponente enthält und die Vertragsentwicklung zu einer regelmäßigen Aktivität wird, beginnt man unweigerlich über eine Optimierung des Prozesses nachzudenken. Es wird offensichtlich, dass das Interface (Vertrag) und die Implementierung (Mikroservice) aufeinander abgestimmt sein müssen, 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.

Das Schema der Mikroservices von Amazon aus einem Tweet von Werner Vogels, CTO von Amazon
Was ist das Dilemma? De facto gibt es zwei Möglichkeiten für die Interaktion von Mikroservices – HTTP Rest und gRPC von Google. Um nicht in das Technologie-Stack von Google involviert zu werden, haben wir uns für HTTP Rest entschieden. Die Annotations zu HTTP REST-Verträgen werden meist in einem der beiden Formate beschrieben: RAML und OAS, früher bekannt als Swagger. Deshalb steht jedes Entwicklerteam vor der Notwendigkeit, sich für einen der Standards zu entscheiden. Doch, wie sich herausstellte, kann diese Entscheidung sehr kompliziert sein.

Warum sind Annotations notwendig?

Eine Annotation ist erforderlich, damit externe Benutzer leicht verstehen, was sie über die HTTP-Schnittstelle Ihres Dienstes tun können. Auf einer grundlegenden Ebene sollte die Annotation mindestens eine Liste der verfügbaren Ressourcen, deren HTTP-Methoden, Anfragekörper, Parameter, notwendige und unterstützte Header sowie Rückgabecodes und Antwortformate enthalten. Ein äußerst wichtiger Bestandteil der Vertragsannotation ist auch deren verbale Beschreibung ("Was passiert, wenn ich diesen Query-Parameter zur Anfrage hinzufüge?", "In welchem Fall wird der Code 400 zurückgegeben?").

Dennoch, wenn es um die Entwicklung einer großen Anzahl von Mikrodiensten geht, möchte man zusätzlichen Nutzen aus den geschriebenen Annotationen ziehen. Beispielsweise können auf Basis von RAML/Swagger sowohl Client- als auch Serverseitencodes in einer Vielzahl von Programmiersprachen generiert werden. Außerdem kann automatisch Dokumentation zu dem Mikrodienst erstellt und auf Ihr Entwickler-Portal hochgeladen werden :).

Beispiel für eine strukturierte Beschreibung eines Vertrags

Es ist weniger verbreitet, dass Mikrodienste basierend auf Vertragsbeschreibungen getestet werden. Wenn Sie sowohl die Annotation als auch die Komponente geschrieben haben, können Sie einen automatisierten Test erstellen, der die Angemessenheit der Funktionsweise des Dienstes mit verschiedenen Eingabedatentypen überprüft. Gibt der Dienst einen Antwortcode zurück, der nicht in der Annotation beschrieben ist? Kann er ungültige Daten korrekt verarbeiten?

Darüber hinaus ermöglicht eine qualitativ hochwertige Umsetzung nicht nur der Verträge 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önnen Designer und Entwickler basierend darauf den Dienst in andere Produkte einführen, ohne zusätzliche Zeitaufwendungen.

Für die Funktion zusätzlicher Werkzeuge haben sowohl RAML als auch OAS die Möglichkeit, Metadaten hinzuzufügen, die im Standard nicht vorgesehen sind (zum Beispiel, so wird das in OAS gemacht).

Im Allgemeinen gibt es im kreativen Einsatz von Verträgen für Mikrodienste ein riesiges Potenzial... zumindest theoretisch

Der Vergleich eines Igels mit einer Natter

Derzeit liegt der Schwerpunkt der Entwicklung bei Acronis auf der Acronis Cyber Platform. Die Acronis Cyber Platform bietet neue Integrationspunkte für 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öffentlichung von APIs erneut die Frage aufgeworfen, welcher Annotationsstandard für unsere Arbeit am besten geeignet ist.

Anfangs schien es, als gäbe es zwei Lösungen – die am häufigsten verwendeten Entwicklungen RAML und Swagger (oder OAS). Tatsächlich stellte sich jedoch heraus, dass es mindestens drei oder mehr Alternativen gibt.

Auf der einen Seite gibt es RAML – eine mächtige und effiziente Sprache. Sie bietet eine gut umgesetzte Hierarchie und Vererbung, wodurch dieses Format besser für große Unternehmen geeignet ist, die viele Beschreibungen benötigen – das heißt, nicht nur ein Produkt, sondern zahlreiche Mikrodienste, die gemeinsame Teile von Verträgen aufweisen – Authentifizierungsschemata, identische Datentypen, Fehlermeldungen.

Der Entwickler von RAML, das Unternehmen Mulesoft, hat sich dem Open API-Konsortium angeschlossen, das sich der Weiterentwicklung widmet. Swagger. 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ührt dazu, dass Swagger, das sich dynamisch weiterentwickelt, in der neuesten – dritten Version – RAML in Bezug auf Flexibilität und Funktionalität fast einholt.

Wäre da nicht eine Kleinigkeit…

Wie sich herausgestellt hat, haben lange nicht alle Open-Source-Tools auf die Version OAS 3.0 aktualisiert. Für Microservices in Go ist das Fehlen einer Anpassung hierfür besonders kritisch. go-swagger auf die neue Version des Standards. Der Unterschied zwischen Swagger 2 und Swagger 3 ist jedoch – enorm. Zum Beispiel haben die Entwickler in der dritten Version:

die Beschreibung von Authentifizierungsschemata verbessert
die Unterstützung für JSON-Schema vervollständigt die Möglichkeit zur Hinzufügung von Beispielen erweitert.
Wir haben die Möglichkeit zur Hinzufügung von Beispielen erweitert

Die Situation wird interessant: Wenn es um die Auswahl des Standards geht, sollten RAML, Swagger 2 und Swagger 3 als separate Alternativen betrachtet werden. Nur Swagger 2 bietet dabei eine gute Unterstützung durch OpenSource-Tools. RAML ist sehr flexibel... und komplex, während Swagger 3 nur schwach von der Community unterstützt wird, sodass Sie gezwungen sind, eigene oder kommerzielle Lösungen zu verwenden, die in der Regel ziemlich teuer sind.

Dennoch bietet Swagger viele angenehme Funktionen, wie ein fertiges Portal. editor.swagger.io, auf den man Anmerkungen hochladen und eine Visualisierung mit detaillierten Beschreibungen, Links und Verbindungen erhalten kann. Für das fundiertere und weniger benutzerfreundliche RAML gibt es diese Möglichkeit nicht. Ja, man kann in Projekten auf GitHub suchen, dort ein Pendant finden und es selbst aufsetzen. Allerdings muss in jedem Fall jemand das Portal warten, was für grundlegende Nutzung oder Testzwecke nicht so praktisch ist. Zudem ist Swagger „weniger dogmatisch“, oder liberal – es kann aus Kommentaren im Code generiert werden, was natürlich dem API-First-Prinzip widerspricht und von keinem der RAML-Tools unterstützt wird.

Zu unserer Zeit haben wir mit RAML als einer flexibleren Sprache begonnen und mussten letztendlich vieles selbst erledigen. Zum Beispiel wird in einem der Projekte ein Tool verwendet, ramlfications in den Unit-Tests, das nur RAML 0.8 unterstützt. Daher mussten wir Workarounds hinzufügen, damit das Tool RAML Version 1.0 verarbeiten konnte.

Muss man überhaupt eine Auswahl treffen?

Nachdem wir uns mit der Erweiterung des Lösungsecosystems für RAML beschäftigt haben, sind wir zu dem Schluss gekommen, dass wir RAML in Swagger 2 konvertieren müssen, um dort alle Automatisierungen, Überprüfungen, Tests und anschließenden Optimierungen durchzuführen. Dies ist ein guter Weg, um sowohl die Flexibilität von RAML als auch die Unterstützung durch die Community-Tools von Swagger gleichzeitig zu nutzen.

Für diese Aufgabe gibt es zwei OpenSource-Tools, die die Konvertierung von Verträgen ermöglichen sollten:

oas-raml-converter – ein derzeit nicht unterstütztes Tool. Bei der Arbeit damit haben wir festgestellt, dass es eine Reihe von Problemen mit komplexen RAMLs gibt, die auf viele Dateien verteilt sind. Dieses Programm ist in JavaScript geschrieben und führt eine rekursive Durchlaufung des Syntaxbaums durch. Aufgrund der dynamischen Typisierung ist es schwierig, diesen Code zu verstehen, weshalb wir uns entschieden haben, keine Zeit mit Patches für dieses veraltete Tool zu verschwenden.
webapi-parser — ein Tool von derselben Firma, das sich rühmt, alles und jedes konvertieren zu können, und das in beide Richtungen. Aktuell wird die Unterstützung für RAML 0.8, RAML 1.0 und Swagger 2.0 angegeben. Allerdings war das Tool zum Zeitpunkt unserer Untersuchung noch SEHR roh und unbrauchbar. Die Entwickler schaffen eine Art IR, was ihnen in Zukunft ermöglichen wird, schnell neue Standards hinzuzufügen. Aber bisher funktioniert das alles einfach nicht.

Und das ist noch nicht alles, mit den Schwierigkeiten, denen wir begegnet sind. Einer der Schritte in unserer Pipeline besteht darin, zu überprüfen, ob das RAML aus dem Repository korrekt in Bezug auf die Spezifikation ist. Wir haben mehrere Tools ausprobiert. Erstaunlicherweise hatten sie alle an unseren Anmerkungen an verschiedenen Stellen und mit völlig unterschiedlichen unsinnigen Worten zu kauen. Und das nicht immer zu Recht : ).

Letztendlich haben wir uns für ein inzwischen veraltetes Projekt entschieden, das ebenfalls eine Reihe von Problemen hat (manchmal stürzt es unerwartet ab, hat Schwierigkeiten beim Umgang mit regulären Ausdrücken). Daher haben wir keinen Weg gefunden, die Validierungs- und Konvertierungsaufgaben mit kostenlosen Tools zu lösen, und haben beschlossen, ein kommerzielles Tool zu verwenden. In Zukunft, wenn die Open-Source-Mittel weiterentwickelt werden, wird die Lösung dieses Problems möglicherweise einfacher. Bis dahin schienen uns die Arbeits- und Zeitaufwendungen für das "Nachbessern" bedeutender zu sein als die Kosten für den kommerziellen Service.

Fazit

Nach all dem möchten wir unsere Erfahrungen teilen und darauf hinweisen, dass Sie vor der Auswahl eines Werkzeugs zur Vertragsbeschreibung klar definieren sollten, was Sie von diesem erwarten und welches Budget Sie bereit sind zu investieren. Auch ohne OpenSource gibt es bereits viele Dienste und Produkte, die Ihnen bei der Überprüfung, Konvertierung und Validierung helfen können. Diese sind jedoch kostspielig, manchmal sogar sehr teuer. Für große Unternehmen sind solche Ausgaben tragbar, doch für ein Startup können sie eine erhebliche Belastung darstellen.

Bestimmen Sie die Werkzeugauswahl, die Sie später verwenden möchten. Wenn Sie beispielsweise einfach nur einen Vertrag anzeigen müssen, ist es einfacher, Swagger 2 zu verwenden, das eine ansprechende API bietet, während Sie bei RAML den Dienst selbst aufsetzen und warten müssten.
Je mehr Aufgaben Sie haben, desto größer wird der Bedarf an Werkzeugen, und diese variieren je nach Plattform. Es ist daher ratsam, sich frühzeitig über die verfügbaren Versionen zu informieren, um eine Wahl zu treffen, die Ihre zukünftigen Kosten minimiert.

Es ist jedoch anzuerkennen, dass alle heute existierenden Ökosysteme unvollkommen sind. Wenn es in einem Unternehmen also Befürworter gibt, die es bevorzugen, mit RAML zu arbeiten, da "es flexiblere Ausdrucksmöglichkeiten bietet", oder andersrum, die Swagger bevorzugen, weil "es verständlicher ist", ist es am besten, ihnen zu erlauben, mit dem zu arbeiten, womit sie vertraut sind und was sie möchten, denn die Werkzeuge der jeweiligen Formate erfordern noch Anpassungen.

Was unsere Erfahrungen betrifft, werden wir in den nächsten Beiträgen erläutern, welche statischen und dynamischen Prüfungen wir auf Basis unserer RAML-Swagger-Architektur durchführen sowie welche Dokumentation wir aus den Verträgen generieren und wie all das funktioniert.

Nur registrierte Benutzer können an der Umfrage teilnehmen. Bitte melden Sie sich an.Sind Sie an Contour interessiert?