🥇Was ist es nun: RAML oder OAS (Swagger)?

In der dynamischen Welt der Mikrodienste kann sich alles ändern – jede Komponente kann in einer anderen Sprache, mit anderen Frameworks und Architekturen neu geschrieben werden. Lediglich die Verträge müssen unverändert bleiben, damit der Mikrodienst von außen auf einer konstanten Grundlage angesprochen werden kann, unabhängig von internen Metamorphosen. Und heute werden wir über unser Problem bei der Auswahl des Formats zur Beschreibung von Verträgen sprechen und die gefundenen Artefakte teilen.

Beitrag verfasst von Anna Melehkova und Vladimir Lapatin

Mikrodienste. Bei der Entwicklung von Acronis Cyber Cloud haben wir erkannt, dass wir nicht um sie herumkommen. Das Design eines Mikrodienstes ist ohne Formalisierung des Vertrags, der das Interface des Mikrodienstes darstellt, unmöglich.

Doch wenn im Produkt mehr als eine Komponente enthalten ist und die Entwicklung des Vertrags zu einer regelmäßigen Tätigkeit wird, beginnt man unweigerlich über die Optimierung des Prozesses nachzudenken. Es wird offensichtlich, dass das Interface (Vertrag) und die Implementierung (Mikrodienst) zueinander passen müssen, dass verschiedene Komponenten dieselben Dinge gleich machen sollten und dass ohne eine zentrale Entscheidung über all diese Aspekte jedes Team gezwungen sein wird, immer wieder Zeit für deren Klärung aufzuwenden.

Das Schema der Mikrodienste von Amazon aus einem Tweet von Werner Vogels, CTO von Amazon
Worin besteht also das Dilemma? De facto gibt es zwei Möglichkeiten, wie Mikrodienste miteinander interagieren – HTTP Rest und gRPC von Google. Um nicht in den Technologiestack von Google involviert zu werden, haben wir uns für HTTP Rest entschieden. Die Annotations für HTTP REST-Verträge werden in der Regel in einem der beiden Formate beschrieben: RAML und OAS, früher bekannt als Swagger. Daher sieht sich jedes Entwicklerteam mit der Notwendigkeit konfrontiert, sich für einen der Standards zu entscheiden. Aber wie sich herausgestellt hat, kann diese Wahl sehr schwierig sein.

Warum sind Annotations erforderlich?

Eine Annotation ist notwendig, damit externe Benutzer leicht verstehen können, was sie über die HTTP-Schnittstelle mit Ihrem Service tun können. Auf einer grundlegenden Ebene sollte die Annotation mindestens eine Liste der verfügbaren Ressourcen, deren HTTP-Methoden, Anfragekörper, eine Auflistung von Parametern sowie die Angabe von erforderlichen und unterstützten Headern sowie Rückgabecodes und Antwortformaten enthalten. Ein äußerst wichtiges Element der Vertragsannotation ist auch ihre verbale Beschreibung („Was passiert, wenn dieser Query-Parameter zur Anfrage hinzugefügt wird?“, „Wann 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 verfassten Annotationsgenerieren. Beispielsweise kann man basierend auf RAML/Swagger nicht nur Client- sondern auch Servercode in einer Vielzahl von Programmiersprachen generieren. Außerdem kann man automatisch Dokumentationen für den Mikrosdienst erhalten und diese auf Ihrem Entwicklerportal hochladen : ).

Beispiel für eine strukturierte Beschreibung des Vertrags

Seltener wird die Praxis des Testens von Mikrodiensten basierend auf Vertragsbeschreibungen angewandt. Wenn Sie sowohl die Annotation als auch die Komponente erstellt haben, können Sie einen automatisierten Test erstellen, der die Angemessenheit der Funktionsweise des Service mit verschiedenen Datentypen als Eingabe überprüft. Gibt der Service einen nicht in der Annotation beschriebenen Antwortcode zurück? Kann er absichtlich falsche Daten korrekt verarbeiten?

Darüber hinaus vereinfacht eine qualitativ hochwertige Umsetzung nicht nur der Verträge, sondern auch der Werkzeuge zur Visualisierung der Annotationsarbeit mit Mikrodiensten. Das heißt, wenn der Architekt den Vertrag qualitativ beschreibt, werden Designer und Entwickler auf dessen Grundlage den Service in andere Produkte integrieren, ohne zusätzliche zeitliche Aufwände.

Für die Arbeit mit zusätzlichen Tools bieten sowohl RAML als auch OAS die Möglichkeit, Metadaten hinzuzufügen, die nicht im Standard vorgesehen sind (zum Beispiel, so wird es in OAS gemacht).

Im Allgemeinen gibt es im kreativen Umgang mit Verträgen für Mikrodienste viel Spielraum… zumindest theoretisch

Ein Vergleich von Igels und Schlangen

Derzeit ist die Entwicklung der Acronis Cyber Platform die Priorität bei Acronis. Die Acronis Cyber Platform bietet neue Integrationspunkte für Drittanbieter-Services mit Acronis Cyber Cloud und der Agentenkomponente. Während unsere internen APIs, die in RAML beschrieben sind, für uns zufriedenstellend waren, hat die Notwendigkeit, APIs zu veröffentlichen, erneut die Frage aufgeworfen: Welcher Standard für Annotations ist am besten für unsere Arbeit geeignet?

Ursprünglich schien es zwei Lösungen zu geben – die am weitesten verbreiteten Entwicklungen RAML und Swagger (oder OAS). Tatsächlich stellte sich jedoch heraus, dass es mindestens nicht zwei, sondern drei oder mehr Alternativen gibt.

Einerseits gibt es RAML – eine leistungsstarke und effiziente Sprache. Die Hierarchie und Vererbung sind gut umgesetzt, sodass dieses Format besser für große Unternehmen geeignet ist, die viele Beschreibung benötigen – also nicht ein Produkt, sondern viele Mikrodienste, die gemeinsame Teile von Verträgen haben – Authentifizierungs-Schemas, identische Datentypen, Fehlerkörper.

Der Entwickler von RAML, die Firma Mulesoft, hat sich dem Open API Consortium angeschlossen, das sich mit der Entwicklung beschäftigt Swagger. Daher hat RAML seine Entwicklung eingestellt. Um sich das Veranstaltungsformat vorzustellen, kann man sich vorstellen, dass die Wartungsmitarbeiter der Hauptkomponenten von Linux zu Microsoft gewechselt sind. Eine solche Situation schafft die Voraussetzungen dafür, Swagger zu nutzen, das dynamisch entwickelt wird und in der letzten – dritten Version – nahezu mit RAML in Bezug auf Flexibilität und Funktionalität Schritt hält.

Wäre da nicht ein Aber...

Wie sich herausstellte, haben längst nicht alle Open-Source-Tools auf die Version OAS 3.0 aktualisiert. Für Mikrodienste in Go ist das Fehlen einer Anpassung go-swagger an die neue Version des Standards am kritischsten. Doch der Unterschied zwischen Swagger 2 und Swagger 3 ist enorm. Beispielsweise haben die Entwickler in der dritten Version:

die Beschreibung der Authentifizierungsschemas verbessert
die Unterstützung von JSON Schema fertiggestellt die Möglichkeit zur Hinzufügung von Beispielen erweitert
Die Situation ist amüsant: Bei der Wahl des Standards müssen RAML, Swagger 2 und Swagger 3 als separate Alternativen betrachtet werden. Dabei hat nur Swagger 2 eine gute Unterstützung durch OpenSource-Tools. RAML ist sehr flexibel... und komplex, während Swagger 3 schwach von der Community unterstützt wird, sodass Sie auf eigene Tools oder kommerzielle Lösungen zurückgreifen müssen, die in der Regel sehr teuer sind.

Es gibt viele angenehme Möglichkeiten in Swagger, wie ein fertiges Portal

Dabei gibt es in Swagger viele nützliche Funktionen, wie ein fertiges Portal. editor.swagger.io, auf dem man eine Annotation hochladen und deren Visualisierung mit detaillierter Beschreibung, Links und Verbindungen erhalten kann. Für das eher fundamentale und weniger benutzerfreundliche RAML gibt es diese Möglichkeit jedoch nicht. Ja, man kann in Projekten auf GitHub nach etwas suchen, einen ähnlichen Ansatz finden und ihn selbst bereitstellen. Aber in jedem Fall muss jemand das Portal unterstützen, was für Basisnutzung oder Testzwecke nicht so praktisch ist. Außerdem ist Swagger „unprinzipiell“, oder sagen wir 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.

Wir haben zu unserer Zeit begonnen, mit RAML als einem flexibleren Format zu arbeiten, und hatten schließlich viel selbst zu tun. Zum Beispiel wird in einem der Projekte das Tool ramlfications in Unit-Tests verwendet, das nur RAML 0.8 unterstützt. Daher mussten wir Hacks hinzufügen, damit das Tool RAML-Versionen 1.0 verarbeiten kann.

Muss man wählen?

Nachdem wir uns mit dem Hinzufügen von Lösungsecosystemen für RAML herumgeschlagen hatten, kamen wir zu dem Schluss, dass wir RAML in Swagger 2 konvertieren müssen und dann darin alle Automatisierung, Überprüfung, Tests und nachfolgende Optimierung durchführen. Dies ist eine gute Möglichkeit, gleichzeitig die Flexibilität von RAML und die Unterstützung des Community-Tools von Swagger 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. Während unserer Arbeit damit fanden wir heraus, dass es eine Reihe von Problemen mit komplexen RAML-Dateien gibt, die auf viele Dateien verteilt sind. Dieses Programm ist in JavaScript geschrieben und führt eine rekursive Traversierung des Syntaxbaums durch. Aufgrund der dynamischen Typisierung wurde es schwierig, in diesem Code klarzukommen, also entschieden wir uns, keine Zeit mit dem Schreiben von Patches für dieses sterbende Tool zu verschwenden.
webapi-parser — ein Tool von derselben Firma, das vorgibt, alles und jedes zu konvertieren, und zwar in jede Richtung. Bis heute wird die Unterstützung von RAML 0.8, RAML 1.0 und Swagger 2.0 angegeben. Allerdings war das Tool zum Zeitpunkt unserer Untersuchung noch ÄUßERST unreif und nicht gebrauchsfähig. Die Entwickler schaffen eine Art IR, was ihnen in Zukunft ermöglicht, neue Standards schnell hinzuzufügen. Aber bisher funktioniert das alles einfach nicht.

Und das ist noch nicht alles an Herausforderungen, mit denen wir konfrontiert waren. Einer der Schritte in unserem Pipeline-Prozess ist die Überprüfung, ob das RAML aus dem Repository korrekt in Bezug auf die Spezifikation ist. Wir haben mehrere Tools ausprobiert. Erstaunlicherweise haben alle unsere Anmerkungen an verschiedenen Stellen mit völlig unterschiedlichen Schimpfwörtern kritisiert. Dabei waren sie nicht immer berechtigt :).

Letztendlich haben wir uns für ein inzwischen veraltetes Projekt entschieden, das auch eine Reihe von Problemen hat (manchmal stürzt es aus heiterem Himmel ab, hat Probleme bei der Verarbeitung von regulären Ausdrücken). So haben wir keinen Weg gefunden, die Validierungs- und Konvertierungsaufgaben mit kostenlosen Werkzeugen zu lösen und beschlossen, auf ein kommerzielles Tool zurückzugreifen. In Zukunft, wenn OpenSource-Mittel weiter fortgeschritten sind, könnte die Lösung dieser Aufgabe einfacher werden. Aber momentan erscheinen uns die Arbeits- und Zeitkosten für "Nachbesserungen" als erheblich höher als die Kosten für den kommerziellen Dienst.

Fazit

Nach alldem wollten wir unsere Erfahrungen teilen und betonen, dass man sich vor der Auswahl eines Werkzeugs für die Vertragsbeschreibung genau darüber klar werden sollte, was man will und welches Budget man bereit ist, zu investieren. Wenn man OpenSource außer Acht lässt, gibt es bereits jetzt eine Vielzahl von Diensten und Produkten, die bei der Überprüfung, Konvertierung und Validierung helfen können. Aber sie sind teuer, manchmal sogar sehr teuer. Für ein großes Unternehmen sind solche Ausgaben tragbar, aber für ein Startup können sie eine große Belastung darstellen.

Bestimmen Sie die Werkzeugauswahl, die Sie später verwenden werden. Wenn Sie nur einen Vertrag anzeigen müssen, ist es einfacher, Swagger 2 zu verwenden, das eine ansprechende API bietet, denn bei RAML müssten Sie den Dienst selbst aufsetzen und betreiben.
Je mehr Aufgaben Sie haben, desto größer wird der Bedarf an Werkzeugen sein, und diese unterscheiden sich je nach Plattform. Es ist ratsam, sich sofort mit den verfügbaren Versionen vertraut zu machen, um eine Wahl zu treffen, die Ihre zukünftigen Ausgaben minimiert.

Es ist jedoch anzuerkennen, dass alle heute existierenden Ökosysteme unvollkommen sind. Wenn es in einem Unternehmen Fans gibt, die gerne mit RAML arbeiten, weil „es flexibleres Denken ermöglicht“, oder umgekehrt Swagger bevorzugen, weil „es verständlicher ist“, dann ist es am besten, sie das tun zu lassen, was sie gewohnt sind und möchten, denn die Werkzeuge eines jeden Formats erfordern Feinarbeit.

Was unsere Erfahrung betrifft, so werden wir in den nächsten Beiträgen über die statischen und dynamischen Prüfungen berichten, die wir auf Basis unserer RAML-Swagger-Architektur durchführen, sowie über die Dokumentation, die wir aus den Verträgen generieren und wie all dies funktioniert.

Nur registrierte Benutzer können an der Umfrage teilnehmen. Bitte einloggen.