­čĹë We're hiring!
Zur ├ťbersicht

Automated REST-Api Code Generation: Wie IT-Systeme miteinander sprechen.

Aktualisiert am 10. Nov. 2020
Automated REST-Api Code Generation- Wie IT-Systeme miteinander sprechen ├ťbersicht

REST steht f├╝r Representational State Transfer. Dieser Architektur-Ansatz beschreibt, wie verteilte Systeme miteinander sprechen k├Ânnen. Denn auch Softwaresysteme stehen auf eine gepflegte Kommunikation.

Wir erkl├Ąren anhand eines Beispiels mit Shopware 6.2.3., warum es sich f├╝r uns immer ├Âfter lohnt, neue Wege zu beschreiten. Keine Angst vor neuen Tools! Denn oft machen sie uns effizienter. 

 

Shopware 6.2.3. und OpenAPI 3.0

Wir standen vor Kurzem bei einem Projekt vor einer altbekannten Aufgabe:

  • Einerseits: Ein Backend mit REST-APIs, mehr oder minder gut dokumentiert. Im konkreten Fall handelte es sich hierbei um Shopware 6.2.3.
  • Andererseits: Ein komplett selbst entwickeltes React-Frontend, das eben diese APIs nutzen soll.
Des Weiteren sollten die verwendete APIs nat├╝rlich vollst├Ąndig im Projekt dokumentiert sein, wie ├╝blich im OpenAPI 3.0 Format. Was machen wir mit dieser Ausgangssituation? 

Shopware API: Der Zufall machtÔÇÖs m├Âglich!

Wir haben uns die aktuelle Shopware 6 Dokumentation zu Gem├╝te gef├╝hrt und festgestellt, dass die von uns ben├Âtigten Funktionen erstens auf verschieden APIs aufgeteilt sind und zweitens noch immer diversen Updates und Wandlungen unterliegen. Hinzu kommt, da├č es im Frontend nat├╝rlich entsprechende API-Zugriffsklassen sowie Model-Klassen geben muss. Und aus der Erfahrung wussten wir, dass gerade das Erstellen der Model-Klassen mit erheblichem Zeitaufwand verbunden ist. Dazu kommt die Gefahr, Dinge zu vergessen. Doch:

Wie es der Zufall so will, stolperten wir im Zuge unserer Recherchen ├╝ber eine automatisch generierte OpenAPI 3.0 Definition der Shopware APIs. Eine spannende Chance, denn: Endlich konnten wir ein Automatisierungstool verwenden! Wie genau?

OpenAPI Generator als L├Âsung

Nach einiger Suche und Vergleichen der Dokumentationen kristallisierte sich ein interessantes Produkt heraus: Der OpenAPI Generator in der aktuellen Release-Version 4.3.1. Ein Vorteil des Tools: Der Generator war eine breite Unterst├╝tzung zum Erzeugen von API ClientsServer-Komponenten in einer wirklich langen Liste von Sprachen, auch wenn wir uns vorerst nur f├╝r den TypeScript-Client interessierten.
 

Unsere Vorgehensweise

  1. Pr├╝fung: Um das Tool und seinen Einsatz f├╝r die aktuellen Aufgaben zu pr├╝fen und auch einzusetzen, extrahierten wir zuerst die OpenAPI 3.0 Spezifikation der Sales Channel API von Shopware.
  2. Installation: Danach wurde der Generator lokal installiert. Bemerkenswert ist die Vielfalt. Direkt ├╝ber Bash, via NPM, Homebrew oder Docker, es bleibt kaum ein Wunsch offen und dauert in der Regel etwa eine Minute.
     

Ein simpler Aufruf wie

openapi-generator generate -g typescript-fetch -o /var/www/output -i api.yaml

erzeugt dann im Verzeichnis /var/www/output/ weitere Verzeichnisse mit den API-Zugriffsklassen und Modellen f├╝r Typescript. Bei rund 15 APIs mit einer Gr├Â├čenordnung von 40 und mehr Modellen ist das eine Menge Ersparnis. Die Anzahl der Modelle ergibt sich ├╝brigens aus den Requests und Responses, welche m├Âglichst genau definiert werden sollten.

Es empfiehlt sich den Elementen, besonders Objekten, klar erkennbare Namen zu geben. Ansonsten werden Modelle mit automatisierten Namen wie InlineResponse2005 vergeben, was der Verwendbarkeit und Wiedererkennbarkeit des erzeugten Codes zuwider l├Ąuft und bei sp├Ąteren Updates auf Grund von einer erneuten Nummerierung der Modelle zu Konflikten und Fehlern f├╝hren kann.

Qualit├Ątskontrolle und Fehlerbehebung

Zur Qualit├Ąt des erzeugten Codes ist zu sagen, da├č er mit wenigen Ausnahmen sogleich verwendet werden kann. Linter zur Qualit├Ątskontrolle sollte man trotzdem ausschlie├čen, da der Code so gut wie keinen Guidelines entspricht. Des weiteren enth├Ąlt die Datei runtime.js eine JS-Variable, die es nicht mehr gibt und daher Fehler verursacht. Au├čerdem werden anyOf, none und ├Ąhnliche Instruktionen aus dem OpenAPI File in teilweise unm├Âgliche TypeScript-Konstrukte mit komplett falscher Syntax ├╝bersetzt. Eine moderne IDE sollte hier aber sofort die entstandenen Probleme anzeigen.

Sobald diese Fehler behoben waren, war die API von Client-Seite aus bereits einsatzbereit und konnte beispielsweise ausden Stores direkt aufgerufen werden.

Funktionell haben die gut leserlich gestalteten API-Zugriffsklassen allerdings einige interessante Dinge zu bieten. So werden zum Beispiel Header- und Authentifizierungsmechanismen auf dem OpenAPI File ├╝bernommen. So k├Ânnen Tokens oder auch OAuth-Pfade in einem einfachen Konfigurationsfile hinterlegt werden.

Das vorhandene Middleware-Interface, dass uns Zugriff auf die internen Funktionen vor und nach dessen Ausf├╝hrung erlaubte, konnten wir nutzen, um den f├╝r dieses Projekt notwendige Authentifizierungsmechanismus anzupassen.

V5.0.0-Beta

Aktuell steht auch eine Beta der Version 5.0 zur Verf├╝gung. Und wie angek├╝ndigt hat sich die ÔÇô zumindest die f├╝r Typescript ├╝berpr├╝fte ÔÇô Codequalit├Ąt erheblich verbessert. Einwandfreies transpillen nach ECMAScript war kein Problem mehr! Man darf also durchaus gespannt sein, was uns bis zum finalen Release noch erwartet.

Ausprobieren und staunen!

Der Aufwand zur Erstellung einer gute definierte API im OpenAPI Format ist mit etwas ├ťbung ├╝berschaubar und meiner Meinung nach sogar zwingend notwendiger Teil der Gesamtdokumentation eines derartigen Projektes. Und ganz bestimmt ist sie die saubere Grundlage zur automatischen Code-Generierung!