Swaggerizing mit Swashbuckle von bestehenden WebApi Schnittstellen

24.07.2018

RESTful- APIs ein großes Problem. Man kann den Server leider nicht fragen, welche Services er anbietet. SOAP- Services bieten eine WSDL an, in der alles genau beschrieben ist, was angeboten wird. Mit Swashbuckle kann man sich den Code generieren lassen, der die Schnittstelle beschreibt. 

Die Spezifikationen von REST- APIs sehen in der Regel folgendermaßen aus:

Action

URI

HTTP Verb

Read all objects

/api/objects

GET

Read object with id 777

/api/objects/777

GET

Create object

/api/objects

POST

Delete object with id 777

/api/objects/777

DELETE

Update object with id 777

/api/objects/777

PUT

 

 

 

Nachdem die API in dieser oder ähnlicher Form spezifiziert wurde kann man Sie mit ASP.Net Wep Api entwickeln.

public class ObjectsController : ApiController

    {

        // GET api/objects

        public IEnumerable<string> Get()

        {

            // Returns all objects

        }

 

        // GET api/objects/777

        public string Get(int id)

        {

            // Returns object with id 777

        }

 

        // POST api/objects

        public void Post([FromBody]string value)

        {

            // Creates object

        }

 

        // DELETE api/objects/777

        public void Delete(int id)

        {

            // Deletes object with id 777

        }

 

        // PUT api/objects/777

        public void Put(int id, [FromBody]string value)

        {

            // Updates object with id 777

        }

 

    }

An dieser Stelle haben wir die API, jedoch fehlt eine Dokumentation zu dem Service. Wir haben leider keine WSDL, die wir einem Entwickler geben können, der diese Schnittstelle anzapfen soll.

Mit Swagger kann man Schnittstellen im Browser dokumentieren. Erstellt man sich diese Swagger Dokumentationen erhält man sehr ansehnliche Dokumentationen im Browser.
  Auf der Swagger -Homepage gibt es auch ein Beispiel mit einem PetShop (siehe https://swagger.io/tools/swagger-editor/).



Jedoch ist es mit einem Riesenaufwand verbunden diese YAML-Files manuell zu erstellen. Um mit weniger Aufwand eine Dokumentation zu erstellen haben wir die Möglichkeit in unserem Projekt ein Nuget-Package hinzuzufügen, welches die Erstellung für uns übernimmt. Dazu muss man zunächst das SwashBuckle-Package herunterladen.

 

Nuget Package Manager öffnen:




Swashbuckle suchen und ein Doppelklick ausführen.

 




Danach die Installation starten.




Die erfolgreiche Installation erkennt man den dem grünen Haken im Nuget Package Manager:




Außerdem gibt es jetzt eine neue Config unter dem App_Start Ordner: SwaggerConfig.cs




Der Code sieht folgendermaßen aus:

 

using System.Web.Http;

using WebActivatorEx;

using Objects.WebApi;

using Swashbuckle.Application;

 

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

 

namespace Objects.WebApi

{

    public class SwaggerConfig

    {

        public static void Register()

        {

            var thisAssembly = typeof(SwaggerConfig).Assembly;

 

            GlobalConfiguration.Configuration

                .EnableSwagger(c =>

                    {

                       

                        c.SingleApiVersion("v1", "Objects.WebApi");

 

                       

                    })

                .EnableSwaggerUi(c =>

                    {

                    });

        }

    }

}

 

 

Wenn man den Browser nun öffnet und localhost/swagger erhält man folgende Ansicht:




Hier hat man dann nicht nur eine komplette Dokumentation der Web Api Schnittstelle, sondern auch einen Testclient. Das bedeutet, dass man auf Tools wie Postman oder SOAPUI für Tests verzichten kann.

 

 

Have fun!





 



 

 

 

 

 

 

zurück