ASP.NET Core Swagger Support hinzufügen

In diesem Artikel zeige ich wie man Swagger Support zu einer ASP.NET Core Anwendung hinzufügt. mit Swagger kann man die API recht einfach und übersichtlich darstellen, dokumentieren und auch einzelne Controller testen. Da Swagger den Inhalt automatisch erstellt hat man nur einmalig bei der Einrichtung Arbeit.

ASP.NET Core Swagger Support hinzufügen

Wer kennt das Problem nicht. Man bekommt Zugang zu einer REST API Schnittstelle und es gibt weder eine Dokumentation noch gute Beispiele. Will man einzelne Funktionen testen muss man erst selber ein Skript schreiben oder die Schnittstelle in einem Programm implementieren. Dank Swagger gehört das der Vergangenheit an.

NuGet Paket installieren

Ausgangsbasis meines Tutorials ist ein frisches Asp.NET Core Projekt mit der API Beispielanwendung WeatherForecast. Über den NuGet Paket Manager installierst du nun das Assembly für Swagger genannt Swashbuckle.AspNetCore hinzugefügt:

Swagger implementieren

Als nächstes fügst du in der Startup.cs Datei in der ConfigureServices Methode folgenden Code hinzu:

services.AddSwaggerGen(options =>
{
  options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
  {
       Title = "My First API",
       Description = "My First Public API",
       Version = "v1"
  });
});

damit wird Swagger injected. Weiter unten in der selben Datei wird nun noch  in der Configure Methode folgendes hinzugefügt:

app.UseSwagger();

app.UseSwaggerUI(options =>
{
  options.SwaggerEndpoint("/swagger/v1/swagger.json", "My First API");
});

Dadurch ist nun Swagger in der HTTP request Pipeline bekannt und durch einen neuen Endpunkt vom Browser aufrufbar.

Test

Die Applikation muss nun neu gebaut werden. Startet man das API Programm wird im Browser die bekannte weatherforecast Ausgabe erzeugt. Ändert man in der URL jedoch den Controllernamen von weatherforecast auf swagger bekommt man die API Dokumentation präsentiert. Bei dieser Beispielapplikation gibt es nur den WeatherForecast Get Request. Ich habe für den Test noch weitere Endpunkte erstellt die direkt über das EntityFramework die Werte aus der Datenbank holen oder dorthin schreiben. Möchte ich also beispielsweise einen neuen User anlegen zeigt mir die Post Dokumentation genau welche Werte gefordert sind und gleich auch Beispielwerte:

Damit nicht genug, du kannst jederzeit über den „Try it out“ Button eine Get Abfrage initialisieren oder einen Post Request mit Daten absenden. Das Interface zeigt den Response der Schnittstelle als Ergebnis an. Erst wenn ich nach ein paar Tests die einzelnen Abfragen verstanden habe setze ich mich zum Programmieren der Client Applikation.

Fazit

Swagger erleichtert dem Anwender eine API das Leben! Nicht nur das, auch als API Entwickler hat man ohne Aufwand eine Beschreibung der Schnittstelle parat und kann den Kunden eine übersichtliche Möglichkeit bieten die einzelnen Requests zu testen. Am Produktivsystem sollte man diese öffentliche Dokumentation dann verstecken oder abschalten. Im nächsten Teil zeige ich wie man den Swagger Support mit 4 Zeilen Code wesentlich verbessern kann.

Teil 1 | Teil 2