Swaggered Development

Mar, 2015

The whole notion of interface based development model is to separate the backend developers from frontend developers by exposing the operations and models. While models represent the entity fields and its properties like required status, max length and other validation characteristics etc, operations represents the restful endpoints or API operations for the client to consume.

Swagger is an API documentation framework that help define the operations and models that are both machine readable and human readable. Swagger exposes json schema (draft3 representation) of operations and models for machine readability and a UI that represents the operations, request, responses, summary, error codes etc for human readability.

By exposing the endpoints information and request and response parameters, you have effectively provided an insight to your operations. On any development project consisting on front end developers and backend developers, its always a waiting game for front end devs as they are dependent on api and its documentation for them to consume and develop. By providing an insight to the operations would allow consuming developers to start immediately mocking the REST service responses.

Much said, let's build a simple swagger doc using Swagger.NET and WebApi.Swagger.net and SwaggerUi can be downloaded as nuget packages.

Once these two packages are installed make sure to have the XML documentation enabled in the project properties of your solution.

To get your API endpoints swaggerified, add XML comments, remarks and parameters information to your Action XML description such as follows:


    public class ValuesController : ApiController
{
 /// 
 /// Gets the resource by the specified ID.
 /// 
 /// The id.
 /// These remarks end up in the implementation notes of swagger
 public string Get(string id)
 {
  return "value";
 }
...

Basically upon compilation, a resource list file (json) is created for machine readability and swaggerUI provides a very neat API explorer and documentation interface for human readability similar to below.

In part 2 of Swaggered Development, I shall show how to generate class files from resource files and also validation.