REST API’s beschreiben mit Swagger

November 1, 2015

Mit Hilfe der Swagger Spezifikation lassen sich RESTful API’s so beschreiben, wie es bei Web Services mit der Web Services Description Language schon immer möglich war.

Swagger beschreibt dabei die Datentypen, Formate und Operationen die das API zur Verfügung stellt in Form einer JSON-Datei, dem "Swagger Specification File". Aus dem Specification File ist es möglich mit Hilfe von Tools, für beliebige Technologien Proxies zu erstellen, die einen typisierten Zugriff auf das API ermöglichen.

Mit Autorest stellt Microsoft ein solches Tool unter Github kostenlos zur Verfügung. Damit lassen sich Clientproxies basierend auf dem Swagger Specification File für unterschiedliche Plattformen generieren. Ein Überblick über Autorest bietet ein Channel 9 Video von Scott Hanselman. Ausserdem besteht in Visual Studio (2013 und 2015) die Möglichkeit, direkt über das Kontextmenu einem Projekt einen Proxy hinzuzufügen. Voraussetzung dafür ist das Azure SDK for .NET ab Version 2.6.

Aus einem ASP.NET Web Api Projekt lässt sich mit Swashbuckle das Swagger Specification File einfach generieren. Mit Hilfe des NuGet Package Manager wird Swashbuckle mit ‘install-package swashbuckle’ installiert und im Projekt referenziert. Nach der Installation kann Swashbuckle über das HttpConfiguration Objekt konfiguriert werden.

using System.Web.Http;
using Swashbuckle.Application;

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Web API routes
        config.MapHttpAttributeRoutes();
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );

        // Swashbuckle
        config.EnableSwagger(f => f.SingleApiVersion("v1", "My Api")).EnableSwaggerUi();
    }
}

Eine komplette Übersicht aller Konfigurationsmöglichkeiten ist unter https://github.com/domaindrivendev/Swashbuckle dokumentiert.

Über die Url http://localhost:PORT/swagger stellt Swashbuckle ein einfaches Frontend zur Verfügung, mit dem auch gleich die API gestestet werden kann. Das Specification File kann nun über http://localhost:PORT/swagger/docs/v1 generiert werden.

Stefan Geiger