Frontend: OpenAPI Generator mit Swagger

Eine präzise Dokumentation deiner Web API ist heutzutage unverzichtbar. Sie zeigt anderen Entwickelnden, welche Aufrufe verfügbar sind und welche Daten übergeben sowie zurückgegeben werden. Noch wichtiger ist jedoch, dass sie die automatische Generierung von Clients ermöglicht. Bei Änderungen an der API profitieren Frontend-Anwendungen und SDKs davon, dass sie zügig angepasst werden können. Die Kombination aus OpenAPI und automatisierter Client-Generierung kann erheblich zur Zeitersparnis und Qualitätserhöhung deiner API-Integrationen beitragen.

Integration von OpenAPI-Spezifikationen

Ein nützliches Format zur Beschreibung von Web APIs ist die OpenAPI-Spezifikation. Tools wie Swashbuckle oder NSwag unterstützen die Integration in ASP.NET Core und erstellen automatisch eine Swagger.json-Datei. Auch ASP.NET Core hat mit .NET 9 von Haus aus mittlerweile eine eigene OpenAPI-Unterstützung. Diese Datei kann in verschiedenen Client-Generatoren verwendet werden, um Clients für unterschiedliche Programmiersprachen und Frameworks zu generieren. Das macht den Prozess nicht nur effizienter und weniger fehleranfällig, sondern erleichtert auch die Nutzung der API durch Dritte.

Effiziente Client-Generierung

Für die Client-Generierung empfiehlt sich der OpenAPI Generator, da er eine breite Palette an unterstützten Programmiersprachen und Frameworks bietet wie z.B. Angular, React und Vue mit TypeScript oder C#. Mit einem einfachen CLI-Befehl kannst du Frontend-Clients direkt von der Konsole aus generieren. Dadurch sparst du Zeit und Ressourcen, da die Erstellung der Clients nicht manuell erfolgen muss, und du kannst rasch auf Änderungen der API reagieren.

openapi-generator-cli generate -g typescript-angular -i WebApi/swagger.json -o src/lib --additional-properties ngVersion=17.0.0

Automatisierte Erstellung in der Build-Pipeline

Ein weiterer Vorteil ist die Möglichkeit, die Swagger.json-Datei während des Kompilierens deines Codes zu erstellen. Dadurch kannst du API-Änderungen in der Build-Pipeline sofort validieren und sicherstellen, dass alle Clients aktuell sind. Das spart dir den Aufwand, die API lokal zu starten, um Clients zu generieren. Überlege, ob generierter Code und die Swagger.json in die Versionsverwaltung aufgenommen werden sollen. Während generierter Code meist aus dem Versionsmanagement herausgehalten wird, kann es vorteilhaft sein, die Swagger.json zu versionieren, um den Status deiner API nachzuvollziehen.

Hier ein Beispiel mit dem CLI Tool von Swashbuckle.

<Project>
    <!-- This target is executed after building a web API project to generate the Swagger JSON file,
        which can be consumed in frontend web apps to generate the frontend clients. -->
    <Target Condition="$(IsWebApiProject)" Name="CreateSwaggerJson" AfterTargets="Build">
        <Exec Command="dotnet swagger tofile --output swagger.json $(OutputPath)$(AssemblyName).dll v1" WorkingDirectory="$(MSBuildProjectDir)" />
    </Target>
</Project>

Ein finales Beispiel könnt ihr dem Open Space Planner entnehmen.

Wie handhabst du die Client-Generierung in deinem Projekt, und welche Erfahrungen hast du dabei gemacht? Schau gerne bei uns auf LinkedIn vorbei und diskutiere mit.