Automatisch Web API Client mit NSwag erstellen

In diesem Tutorial zeige ich, wie man automatisiert von einer Web API einen Client mit NSwag erstellen kann. Mit dem Tool verringert sich der implementierungsaufwand bei der Arbeit mit der eigenen Web API, für eine Microservice Architektur eine tolle Komfortfunktion.

Automatisch Web API Client mit NSwag erstellen

Wer mit Microservice arbeitet kennt es, den Aufwand zig Schnittstellen zu implementieren. Wäre es nicht toll, wenn man sich den Clientcode für eine über Swagger dokumentierte Schnittstelle automatisch generieren lassen zu können? Mit NSwag ist das für .NET Projekte möglich. Die folgenden Schritte zeigen wie man einen Client aus einem bestehenden Web API Projekt heraus erstellt.

Schritt 1: NSwag dem Web API Projekt hinzufügen

Sofern die API noch keine Swagger Seite besitzt lässt sich diese mit der NSwag Middleware hinzufügen. Dazu fügt man das NSwag.AspNetCore NuGet hinzu:

In der Startup.cs in der ConfigureServices Methode fügt man folgenden Code hinzu:

// Register the Swagger services
services.AddSwaggerDocument();

weiter unten in der Configure Methode muss die Middleware noch registriert werden:

// Register the Swagger generator and the Swagger UI middlewares
app.UseOpenApi();
app.UseSwaggerUi3();

Schritt 2: Web API Projekt publishen

Das NSwagstudio benötigt neben dem Assembly des Web API Projekts auch noch die Abhängigkeiten. Beides kommt man am einfachsten, wenn man das Projekt veröffentlicht (publish). Das geht in Visual Studio so:

Im folgenden Dialog wählt man Folder und lässt am besten die Default Einstellungen und führt die Veröffentlichung aus.

Schritt 3: Client Class Library Projekt erstellen

Bevor man sich nun dem NSwagStudio widmet legt man am besten noch ein Client Projekt an. Ein .NET Bibliotheksprojekt in dem der Client später für alle Services die auf die Schnittstelle zugreifen möchten zur Verfügung steht. Das Projekt kann leer bleiben wie vom Assistenten erstellt.

Schritt 4: NSwagStudio installieren und starten

Das NSwagStudio gibt es auf der GitHub Seite des Projekts als Download. Im geöffneten Studio gibt es mehrere Möglichkeiten einen Client für eine API zu erstellen. Da wir die API selber programmieren und das Assembly gebaut haben können wir dieses (zuvor veröffentlichte) Assembly als Quelle angeben. Anbei meine Einstellungen im Input Teil:

Ist der Input definiert geht es auf der rechten Seite des Programms zur Definition des Outputs. Man hat sehr viele Optionen, idealerweise belässt man diese für den ersten Export. Später kann man die Werte anhand der persönlichen Vorlieben ändern. Der Client Code wird, einmal definiert, jedes Mal neu erstellt. Ich habe für das beschriebene Setup folgende Einstellungen gemacht und danach den Code generieren lassen:

Alternative

Sofern man keinen Zugriff auf die Assembly des Web API Projekts hat sondern nur die Swagger Schnittstelle der API hat gibt es folgende Alternative. Im Input Bereich von NSwagstudio kann man auch eine Swagger Spezifikation angeben. Dort fügt man den Link zur swagger.json Datei ein und erzeugt eine lokale Kopie.

Alle folgenden Schritte im Output Bereich bleiben gleich wie weiter oben beschrieben.

Client verwenden

Die erstellte Client Bibliothek kann man nun in einem Projekt verwenden und die API dadurch abstrahiert benutzen. Am einfachsten lassen sich die automatisch erstellten Klassen in einer einfachen Konsolenapplikation auf Funktionalität testen. Alternativ dazu kann man auch ein Unit Test Projekt erstellen.

Der Client muss instanziert werden, danach lassen sich die einzelnen Endpunkte mit den definierten Parametern aufrufen. Der Screenshot zeigt, dass der automatisch generierte Code in meiner ersten Version schwer zu verwenden ist, da alle 3 Get Methoden für Driver automatisiert mit Driver benannt werden und der Generator eine Zahl anhängt. Da muss ich das Namensschema anpassen.

Fazit

NSwag ist ein nettes Tool um den Prozess der Schnittstellenimplementierung zu beschleunigen.