Tipps und Tricks rund um .NET und Visual Studio

Swashbuckle zur Generierung von Dokumentationen für Web-APIs konfigurieren
Keine Kommentare

Dr. Holger Schwichtenberg (MVP) und FH-Prof. Manfred Steyer teilen in der Kolumne “.NETversum” ihr Expertenwissen rund um .NET-Tools und WPF mit.

Wie in einem vorangegangenen Tipp beschrieben, bietet das freie Communityprojekt 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 Servicebeschreibung, die 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, die 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 in Listing 1 veranschaulicht dies. Der Parameter c des Lambda-Ausdrucks steht für ein Konfigurationsobjekt, das die einzelnen Konfigurationsoptionen anbietet. Durch Aufruf der Methode ResolveConflictingActions wird festgelegt, wie Swashbuckle vorgehen soll, wenn für ein und denselben URL mehrere Serviceoperationen existieren. Dieser eine Fall ergibt sich, wenn das Web-API zwischen mehreren Serviceoperationen lediglich anhand der übergebenen URL-Parameter wählen muss.

Listing 2 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 das Web-API erstere heran; ansonsten letztere. Auch wenn es auf den ersten Blick so wirken mag, verursacht die dritte Methode in Listing 2 keinen Konflikt, da sie durch die standardmäßig vorherrschende Route auf den 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 (Listing 1) angeben, wie mit solchen Konflikten umzugehen ist. Dazu verweist diese Option auf einen Lambda-Ausdruck, 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 zu retournieren, die für den jeweiligen URL in das Swagger-Dokument aufzunehmen sind. 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 des Web-API im Hinterkopf, kann er hingegen solche Konflikte bereits von vorn herein vermeiden, indem er jeder Operation einen eigenen URL verpasst sowie Überladungen zugunsten von optionalen Parametern vermeidet.

Listing 1
GlobalConfiguration.Configuration.EnableSwagger(c => { 

  c.ResolveConflictingActions(descriptions =>
    {
      var result = descriptions.First();
      return result;
    });
});
Listing 2
public class HotelController : ApiController
{
  [HttpGet]
  public List<Hotel> FindHotelsBySterne(int minSterne)
  {
    […]
  }

  public List<Hotel> GetHotels()
  {
    […]
  }

  /// <summary>
  /// Liefert ein Hotel anhand der übergebenen ID zurück.
  /// </summary>
  public Hotel GetHotel(int id)
  {
    […]
  }
}

Eine weitere nützliche Konfigurationsoption, die hier vorgestellt werden soll, ist die Möglichkeit, mit IncludeXmlComments die Informationen aus XML-basierten Kommentaren, wie jene, die in Listing 2 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 Tipp eine Herausforderung, die sich ergibt, wenn eine Serviceoperation 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) { […] }
Unsere Redaktion empfiehlt:

Relevante Beiträge

Abonnieren
Benachrichtige mich bei
guest
0 Comments
Inline Feedbacks
View all comments
X
- Gib Deinen Standort ein -
- or -