Digital First: Loading

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

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!

Mehr Blogartikel zum Thema:

2020-08-regex-titelbild-auszug
Regex: Zeichenfolgen schnell und effizient überprüfen
Symfony_&_Vue_Blog
Symfony & Vue.js: der Stack der Zukunft
Fastlane_React_Native
Mobile Apps: Effizientes Deployment mit fastlane
loading
Nach oben