Im Bereich verteilter Systeme gehört die Generierung clientseitiger Proxys seit Jahrzehnten zum Alltag. Die Aufgabe dieser Proxys 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, welche jener des Services 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 Service-Technologien Interfacebeschreibungssprachen entwickelt. Ein sehr bekannter Vertreter ist die Web Service Description Language (WSDL), welche in erster Linie zum 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 [1] 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 [2], existiert mit Swashbuckle [3] 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 die 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 wieder findet, weist eine Methode Register auf, welche Swashbuckle konfiguriert. Diese Methode wird über ein Attribut PreApplicationStartMethod referenziert und somit im Zuge des Startups 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 der Web API konfiguriert wird, zu aktivieren. Informationen dazu findet man unter [2].
Nach dem Start der Web-Anwendung, erhält der Entwickler durch Aufruf der Url /swagger/docs/v1 eine nach den Vorgaben von Swagger generierte Beschreibung der von ihm bereitgestellten Web API. Dabei handelt es sich um ein JSON-Dokument, welches die einzelnen Urls sowie die unterstützten Verben und erwarteten Nachrichten beschreibt. Durch Aufruf der Url /swagger gelangt der Entwickler zu einer aus diesem JSON-Dokument generierten interaktiven Dokumentation, über welche er die einzelnen Service-Operationen auch zum Testen direkt anstoßen kann (siehe Abbildung).
Für das Generieren von clientseitigen Proxies stehen zahlreiche Projekte aus der Community zur Verfügung. Eines davon ist Swagger.WebApiProxy [4], welches in einem weiteren Tipp näher betrachtet wird.
Links