Zurück

Warum geht der Backend-Aufruf nicht mehr?

von Thomas Czogalik

Kennst Du das Phänomen, dass Backend Aufrufe immer wieder zu Laufzeitfehlern führen? In meinem Team haben wir festgestellt, dass bei Änderungen oder Erweiterungen im Backend die entsprechenden Anpassungen im Frontend nicht gemacht wurden

Wie kann man dieses Problem beheben? In unserem Projekt haben wir den OpenAPI Generator eingesetzt, der dafür sorgt, dass schon beim Frontend Build Kompilierfehler generiert werden, wenn sich im Backend etwas geändert hat.

Mit OpenAPI Generator lassen sich ganz einfach API-Client-Libraries [1] generieren, die im jeweiligen Frontend eingebunden und verwendet werden können. Dabei wird eine Vielzahl an Programmiersprachen unterstützt, z.B. JavaScript oder TypeScript, was das Einbinden in gängige Frontend-Technologien wie Angular, React oder Vue.js ermöglicht.

Im Folgenden stelle ich eine kleine Demo unseres Ansatzes vor:

Wir nutzen ein SpringBoot-Backend mit Kotlin und ein Angular-Frontend. Als Build Tool setzen wir Gradle ein. Maven ist auch eine Alternative. Im Folgenden konzentrieren wir uns auf die Konfiguration des OpenAPI Generators. Wer Interesse am gesamten Beispiel hat, findet dieses auf GitHub [2].

Um eine OpenApi-Spezifikation zu generieren, muss das OpenApi Generator Plugin in der build.gradle oder pom.xml eingebunden werden.

 

plugins {
  id "org.openapi.generator" version "5.3.0"
}
Build.gradle.kts

Durch das Einbinden erhalten wir Zugriff auf verschiedene Gradle Tasks, darunter openApiGenerators, der eine Liste aller verfügbaren Generatoren liefert und dem openApiGenerate, welcher aus der OpenApi Spezifikation eine API-Client-Library generiert. Letzterer benötigt einige Eingabe Parameter. Dazu fügen wir folgenden Code in unsere build.gradle ein:

openApiGenerate {
    generatorName.set("typescript") // (1)
    inputSpec.set("$rootDir/specs/api-docs.json") // (2)
    outputDir.set("$buildDir/generated") // (3)
}
Build.gradle.kts

(1)    Der Generatorname, der aus dem openApiGenerators Task entnommen werden kann. Hier wird der TypeScript-Generator, der eine TypeScript-Library generiert.
(2)    Der Speicherort für die Open API 2.0/3.x Spezifikation
(3)    Der Speicherort für den generierten API-Client

Nun kann der Task gestartet werden. Befindet sich eine OpenApi Spezifikation in dem angegebenen Pfad, wird aus ihr eine API-Client-Library generiert.

Anschließend kann die generierte API-Client-Library in ein Frontend eingebunden werden.

Die vorgestellte Implementierung zeigt nur die Grundlagen und kann weiter ausgebaut werden. In unserem Projekt haben wir z.B. den Input der Spezifikation abhängig davon gemacht, auf welcher Umgebung der Build läuft. Bei uns wurde sie aus dem lokal laufenden Backend und auf dem Buildserver aus einem Git-Repository heruntergeladen. Außerdem wurde der openApiGenerate Task in unseren Build-Task aufgenommen und läuft vor unseren Frontend-Tests. Damit haben wir unser Ziel erreicht und Änderungen am Backend führen schon während dem Build zu Kompilier- und nicht erst zu Laufzeitfehlern.

Quellen/Links

  [1] https://github.com/OpenAPITools/openapi-generator/
  [2] https://github.com/thomcz/ng-swagger-gen-example
Zurück