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.

Veröffentlicht von Norbert Eder

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

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Cookie-Einstellungen
Auf dieser Website werden Cookie verwendet. Diese werden für den Betrieb der Website benötigt oder helfen uns dabei, die Website zu verbessern.
Alle Cookies zulassen
Auswahl speichern
Individuelle Einstellungen
Individuelle Einstellungen
Dies ist eine Übersicht aller Cookies, die auf der Website verwendet werden. Sie haben die Möglichkeit, individuelle Cookie-Einstellungen vorzunehmen. Geben Sie einzelnen Cookies oder ganzen Gruppen Ihre Einwilligung. Essentielle Cookies lassen sich nicht deaktivieren.
Speichern
Abbrechen
Essenziell (1)
Essenzielle Cookies werden für die grundlegende Funktionalität der Website benötigt.
Cookies anzeigen