Tipps und Tricks rund um .NET und Visual Studio

Web APIs mit Swagger dokumentieren
Kommentare

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

Im Bereich verteilter Systeme gehört die Generierung clientseitiger Proxies seit Jahrzehnten zum Alltag. Die Aufgabe dieser Proxies ist es, unter Verwendung des gewählten Netzwerkprotokolls und Datenformats mit einem Service zu kommunizieren. Nach außen hin bietet der Proxy eine Schnittstelle an, die jener des Service gleicht. Diese Schnittstelle kann der Client nutzen, um serverseitige Operationen anzustoßen, ohne sich mit den Details der Netzwerkprogrammierung auseinandersetzen zu müssen.

Um Proxies generieren zu können, bedarf es einer formalen Beschreibung der angebotenen Services. Für diesen Zweck wurden für zahlreiche Servicetechnologien Interfacebeschreibungssprachen entwickelt. Ein sehr bekannter Vertreter ist die Web Services Description Language (WSDL), die in erster Linie zur Beschreibung SOAP-basierter Web Services zum Einsatz kommt. Für RESTful Services bzw. Web APIs hat sich noch kein solcher Standard auf breiter Basis durchgesetzt. Allerdings hat die Beschreibungssprache Swagger in der letzten Zeit sehr viel Unterstützung erfahren, sodass heute für fast jede Plattform Swagger-Unterstützung zumindest durch Erweiterungen aus der Community vorliegen.

Während auch für ASP.NET MVC 6 eine Unterstützung für Swagger geplant ist, existiert mit Swashbuckle ein ausgereiftes quelloffenes Projekt, das heute schon das Generieren von Swagger-Dokumentationen für ASP.NET-Web-API-basierte Projekte ermöglicht. Der Entwickler kann Swashbuckle via NuGet in ein Web-API-Projekt laden. Hostet er Web API in IIS, muss er dazu lediglich das Paket Swashbuckle einbinden. Im Zuge dessen erhält er auch im Ordner App_Start eine Datei SwaggerConfig.cs generiert. Die gleichnamige Klasse, die sich darin befindet, weist eine Methode Register auf, die Swashbuckle konfiguriert. Diese Methode wird über ein Attribut PreApplicationStartMethod referenziert und somit im Zuge des Start-ups innerhalb von IIS ohne weiteres Zutun des Entwicklers zur Ausführung gebracht.

Nutzt der Entwickler hingegen Self-Hosting, ist laut Dokumentation das NuGet-Paket Swashbuckle.Core zu beziehen. In diesem Fall wird Swashbuckle durch Aufruf von Erweiterungsmethoden, die für die Klasse HttpConfiguration mit Web API konfiguriert werden, aktiviert. Informationen dazu findet man unter hier.

Nach dem Start der Webanwendung erhält der Entwickler durch Aufruf des URL /swagger/docs/v1 eine nach den Vorgaben von Swagger generierte Beschreibung des von ihm bereitgestellten Web API. Dabei handelt es sich um ein JSON-Dokument, das die einzelnen URLs sowie die unterstützten Verben und erwarteten Nachrichten beschreibt. Durch Aufruf des URL /swagger gelangt der Entwickler zu einer aus diesem JSON-Dokument generierten interaktiven Dokumentation, über die er die einzelnen Serviceoperationen auch zum Testen direkt anstoßen kann (Abb. 1).

Abb. 1: Interaktive via Swagger generierte Dokumentation

Abb. 1: Interaktive via Swagger generierte Dokumentation

Für das Generieren von clientseitigen Proxies stehen zahlreiche Projekte aus der Community zur Verfügung. Eines davon ist Swagger WebApiProxy, das im folgenden Tipp näher betrachtet wird.

Clientseitige Proxies für Web APIs generieren

Das quelloffene Projekt Swagger WebApiProxy bietet dem Entwickler die Möglichkeit, aus einer Swagger-basierten Beschreibung eines RESTful Services bzw. eines Web API einen clientseitigen Proxy zu generieren.

Die einfachste Art, diese Communityerweiterung zu nutzen, besteht darin, sie von GitHub herunterzuladen und das sich unterhalb des Ordners src befindliche Projekt Swagger.WebApiProxy.Template in die eigene Solution einzubinden. Zwar ist es auch möglich, es via NuGet zu beziehen. Allerdings geht dies mit der Notwendigkeit einer wie hier beschriebenen manuellen Änderung der genutzten Projektdatei einher.

Das Projekt Swagger.WebApiProxy.Template besteht im Wesentlichen aus einer T4-Datei, die sich um das Generieren der gewünschten clientseitigen Proxies kümmert. Die dazu nötigen Informationen bezieht sie aus der Datei SwaggerApiProxy.tt.settings.xml, in die unter anderem der URL des Swagger-Dokuments sowie der Namensraum, in dem der Proxy generiert werden soll, einzutragen ist. Listing 1 demonstriert dies. Das Element URL spiegelt den URL des Dokuments wider und das Element Namespace den gewünschten Namensraum. Unter Id findet man einen Bezeichner für das Web API. Die restlichen Elemente wurden aus der mitgelieferten Beispieldatei ohne Änderung übernommen.

  
    
    
      SwaggerServer
      http://localhost:59458/swagger/docs/v1
      SwaggerServer
      WebProxy
      Swagger.WebApiProxy.Template.BaseProxy
      (Uri baseUrl) : base(baseUrl)
      false
      false
    
    
  

Anschließend kann man mit dem generierten Proxy auf Web API zugreifen. Listing 2 veranschaulicht dies, indem es zwei beispielhafte Serviceoperationen, GetHotel und FindHotelsBySterne, anstößt.

HotelWebProxy proxy = new HotelWebProxy(new Uri("http://localhost:59458"));
var hotel = proxy.Hotel_GetHotel(1).Result;
var hotels = proxy.Hotel_FindHotelsBySterne(3).Result;
Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -