Wie in einen vorangegangenen Beitrag beschrieben, bietet das freie Community-Projekt Swashbuckle die Möglichkeit, für mit ASP.NET Web API bereitgestellte Services ein Swagger-Dokument zu erzeugen. Dabei handelt es sich um eine JSON-basierte Service-Beschreibung, welche zum Generieren von Dokumentationen oder clientseitigen Proxys genutzt werden kann.
Swashbuckle bietet zahlreiche Konfigurationsmöglichkeiten, von denen drei hier näher betrachtet werden. Um diese Konfigurationsmöglichkeiten zu nutzen, übergibt der Entwickler einen Lambda-Ausdruck an die Methode EnableSwagger, welche Swashbuckle aktiviert. Bei EnableSwagger handelt es sich um eine Erweiterungsmethode für die Klasse HttpConfiguration, mit der ASP.NET Web API konfiguriert wird.
Das Beispiel im nächsten Listing veranschaulicht dies. Der Parameter c des Lambda-Ausdrucks steht für ein Konfigurationsobjekt, welches die einzelnen Konfigurationsoptionen anbietet. Durch Aufruf der Methode ResolveConflictingActions wird festgelegt, wie Swashbuckle vorgehen soll, wenn für ein und dieselbe Url mehrere Service-Operationen existieren. Solch ein Fall ergibt sich, wenn Web API zwischen mehreren Service-Operationen lediglich anhand der übergebenen Url-Parameter wählen muss. Das nächste Listing veranschaulicht dies anhand eines einfachen Controllers, da hier die standardmäßig vorherrschende Route dazu führt, dass ASP.NET Web API die ersten beiden Operationen bei einer an /api/hotel gerichteten GET-Anfrage in Erwägung zieht. Übersendet der Aufrufer einen Parameter minSterne zieht Web-API erste heran; ansonsten letztere. Auch wenn es auf dem ersten Blick so wirken mag, verursacht die dritte Methode in Listing 4 keinen Konflikt, da sie durch die standardmäßig vorherrschende Route auf die Url /api/hotel/{id} abgebildet wird, wobei {id} ein Platzhalter für den gleichnamigen Übergabeparameter ist.
Leider unterstützt Swagger diese Art der (Methoden-)Überladung nicht und löst in solchen Fällen eine Ausnahme aus. Um diese Ausnahme zu vermeiden, kann der Entwickler jedoch über die Konfigurationseinstellung ResolveConflictingActions (siehe nächstes Listing) angeben, wie mit solchen Konflikten umzugehen ist. Dazu verweist diese Option auf einen Lambdaausdruck, der pro Konflikt eine Auflistung mit Informationen zu sämtlichen in Konflikt stehenden Operationen übergeben bekommt und die Aufgabe hat, ein Objekt mit jenen Informationen, die für die jeweilige Url in das Swagger-Dokument aufzunehmen sind, zu retournieren. Im betrachteten Fall wird einfach die erste Beschreibung retour geliefert und somit alle anderen Operationen außer Acht gelassen. Es wäre hingegen auch denkbar sämtliche Beschreibungen zu einer einzigen Beschreibung zu vereinen.
Hat der Entwickler diese Einschränkung beim Implementieren der Web API im Hinterkopf, kann er hingegen solche Konflikte bereits von vorn herein vermeiden, indem er jeder Operation eine eigene Url verpasst sowie Überladungen zugunsten von optionalen Parametern vermeiden.
GlobalConfiguration.Configuration.EnableSwagger(c => {
c.ResolveConflictingActions(descriptions =>
{
var result = descriptions.First();
return result;
});
});
public class HotelController : ApiController
{
[HttpGet]
public List FindHotelsBySterne(int minSterne)
{
[…]
}
public List GetHotels()
{
[…]
}
///
/// Liefert ein Hotel anhand der übergebenen Id zurück.
///
public Hotel GetHotel(int id)
{
[…]
}
}
Eine weitere nützliche Konfigurationsoption, die hier vorgestellt werden soll, ist Möglichkeit, mit IncludeXmlComments die Informationen aus XML-basierten Kommentaren, wie jene, die im nächsten Listing für die Methode GetHotel hinterlegt wurden, in die generierte Swagger-Dokumentation aufzunehmen. Dazu ruft der Entwickler IncludeXmlComments im Rahmen der Konfiguration auf und übergibt dabei einen String, der den vollständigen Dateinamen der beim Kompilieren generierten XML-Datei beinhaltet:
c.IncludeXmlComments(
System.AppDomain.CurrentDomain.BaseDirectory
+ @"\bin\SwaggerServer.XML");
Damit Visual Studio diese XML-Datei beim Kompilieren generiert, muss in den Projekteinstellungen unter Build die Option XML documentation file aktiviert werden.
Zum Abschluss betrachtet der vorliegende Beitrag eine Herausforderung, die sich ergibt, wenn eine Service-Operation den Typ HttpResponseMessage oder IHttpActionResult retourniert. In diesem Fall ist Swashbuckle nicht in der Lage, via Reflektion den über die Nutzdaten übersendeten Rückgabewert zu erkennen. Abhilfe schafft hier das Attribut ResponseType, über das der Entwickler über den tatsächlichen Rückgabewert informieren kann:
[ResponseType(typeof(Hotel))]
public HttpResponseMessage PostHotel(Hotel hotel) { […] }
Links