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:
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.