.NET Core API mit Swagger/OpenAPI dokumentieren - Norbert Eder

Die OpenAPI Specification erlaubt die Beschreibung von RESTful APIs. Damit können diese nicht zur spezifiziert, sondern auch dokumentiert werden. Eine Vielfalt an Tools unterstützt beim Schreiben einer Spezifikation, bei der Generierung von Server- und Client-Code, sowie bei der Dokumentation.

Besteht nun bereits eine entsprechende API auf Basis .NET Core, dann kann eine Spezifikation bzw. Dokumentation mit einigen wenigen Handgriffen bereitgestellt werden.

Konfiguration

Die Installation des Nuget-Paketes Swashbuckle.AspNetCore stellt alles Notwendige bereit:

Install-Package Swashbuckle.AspNetCore

Alle weiteren Anpassungen sind in der Startup.cs durchzuführen.

In ConfigureServices muss der Generator registriert werden:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("1", new Info { Title="Project", Version = "1"});
});

In der Methode Configure wird die Verwendung mit app.UseSwagger() aktiviert. Damit wird das generierte JSON unter /swagger/1/swagger.json zur Verfügung gestellt. Möchte man diese in einer schönen Oberfläche, dann erreicht man dies durch:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/1/swagger.json", "Projektlogger2 API v1");
});

Das UI ist am Endpunkt /swagger erreichbar. Hier ein visuelles Beispiel:

Swagger Dokumentation | Norbert Eder

Es ist dabei zu beachten, dass alle API-Aktionen und Parameter, die nicht Teil der Routen-Definition sind, durch entsprechende Bindungen markiert sind:

[HttpPost]
public IActionResult Insert([FromBody]Ticket newClientTicket)
{
    ...
}

Fazit

Das verwendete Paket ist sehr gut dokumentiert und hilft bei sehr vielen Themen weiter bzw. zeigt alle vorhandenen Möglichkeiten auf. Die erhaltende Dokumentation hilft etwaigen Verwendern der Schnittstelle weiter und kann ohne Zusatzaufwand aktuell gehalten werden. Zudem kann die generierte Spezifikation auch maschinell weiterverarbeitet werden.

Über den Autor

Norbert Eder

Ich bin ein leidenschaftlicher Softwareentwickler und Fotograf. Mein Wissen und meine Gedanken teile ich nicht nur hier im Blog, sondern auch in Fachartikeln und Büchern.