ASP.NET Core Swagger Support optimieren

Im letzten Artikel habe ich gezeigt wie man den ASP.NET Core Swagger Support hinzufügen kann. Nun werden wir die Dokumentation der Datenmodelle im Swagger Output hinzufügen und den Endpunkt der Dokumentation verschieben.

ASP.NET Core Swagger Support optimieren

Nachdem Swagger nun bereits die einzelnen Endpunkte gut dokumentiert kann man bereits zufrieden sein. Mit ein wenig Feintuning lässt sich die Dokumentation aber noch wesentlich verbessern und als API Entwickler erspart man sich so schnell mal die ein oder andere Rückfrage.

Dokumentation der Datenmodelle hinzufügen

Aktuell zeigt mir Swagger beim Schema die Variablen des Datenmodells an:

Ein guter Entwickler hat bereits sprechende Variablennamen definiert, jedoch wäre ein kurzer Satz mit weiterführenden Informationen gut. Trifft der Anwender auf diese Dokumentation und kennt die Thematik nicht könnten ihm sogar sprechende Namen wenig sagen. Der Anwender muss wissen welche Daten er in welches Feld schreiben muss. Beim Datenmodell legt man wie folgt weitere Informationen ab:

Eine so genaue Dokumentation im Code ist wünschenswert, vor allem bei Datenmodellen, aber mal ehrlich: wer macht das schon? Startet man die Webapplikation neu zeigt sich noch kein Erfolg, im Projekt sind noch folgende Änderungen vorzunehmen:

Damit wird die XML-Dokumentationsdatei aktiviert und im angegebenen Pfad erstellt. In der Startup.cs in der ConfigureService Methode gibst du Swagger noch bekannt wo diese erstellte Dokumentations-XML zu finden ist:

var fileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
options.IncludeXmlComments(filePath);

Mit dem Code aus dem letzten Tutorial sieht das in etwa wie folgt aus:

Jetzt nur noch neu bauen und Swagger zeigt ein dokumentiertes User Modell:

Swagger im Root anzeigen

Aktuell startet die Applikation noch mit der WeatherForecast Get Abfrage und man erreicht Swagger nur durch Eingabe von Swagger in der URL. Lässt man die Controllernamen weg zeigt die Root Seite der Anwendung einen 404 Fehlerseite. Da wir eine API bereitstellen wäre es doch fein, wenn die Root Seite die Swagger Dokumentation zeigt. Damit können auch Entwickler die Swagger nicht kennen diese tolle API Dokumentation finden. Damit das klappt ist genau eine Zeile Code in der Configure Methode in der Startup.cs Datei nötig:

options.RoutePrefix = "";

Der gesamte Code sieht wie folgt aus:

Das Ergebnis spricht für sich:

Fazit

Mit lächerlichen 4 Zeilen neuem Code hat man Swagger deutlich verbessert und die eigene API noch Benutzerfreundlicher gestaltet. Als Entwickler muss man nun nur noch darauf achten, dass die Abfragen alle Funktionieren und die Datenmodelle soweit möglich selbsterklärend dokumentiert werden. Die Anwender dürfen sich auf eine schöne REST API freuen.

Teil 1 | Teil 2