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!
