Have you ever wondered if there was an quick alternative to the Fiddler and the Advanced Rest Client /Postman for that matter.Something that would be pretty close to code that can be helpful in documentation and help you quickly get up to speed on testing your restful API’s? Well of late Swagger has been pretty popular because its open source and its ease of configuration.Well you can be up and running in 5 min.Swagger helps us to build pretty solid rest API documentation . Do you want to read on or do you want to get into the thick of it?
Step 1 :Let us just go ahead and select the most common ASP.Net MVC application and select WEB API as Project Template.Just hit F5 and you can see that by default the project has two Controllers Home and Values. We will concentrate on ValuesController as it seems to have some methods exposed.Well once you have the project up and running you will notice that the web project hosted via IISExpress on some port will have a API option on the top left hand on the home page.Clicking on it will lead to http://localhost:[portnumber]/Help which will provide some basic documentation on the webapi exposed.But you will soon see how much more convenient ,user friendly and testable Swagger is.
Step 2 :Time to fire up Swagger from nuget packages.To help us set it up in ASP.NET there is a open source project called Swashbuckle .
Type in the following in Nuget Package Manager Console.
Install-Package swashbuckle
Expanding the App_Start folder in your SolutionExplorer you can see the SwaggerConfig.cs magically inserted with some default options set.Basically ensure that you have at least the following configuration under SwaggerConfig.Register() method.
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c => c.SingleApiVersion(“v1”, “A title for your API”))
.EnableSwaggerUi();
Thats pretty much it .And you can run it and hit the below url to go to swagger url
http://localhost:%5Bportnumber%5D/swagger
Well you can now click on the Get url ,expand it and hit the try it button to see the request url,response body,response code as well as the response header.You can pass in the required parameters as you can discover using the second Get url.
You can also add xml documentation by linking the document to swagger in the SwaggerConfig.cs
First you will have to enable the xml documentation in Build tab under project properties .Next you will have to add the following line to EnableSwagger()
c.IncludeXmlComments(filePath:System.AppDomain.CurrentDomain.BaseDirectory + “[name of xml file mentioned under build tab]”);
And just restart the application.
So you can see your xml comments reflected now.Cool isnt it?
You can even add Implementation Notes by adding remarks tag in your xml comments.You can also add HTML elements into the remarks tag if you are interested like adding a table inside the remarks tag.
To add response type schema you will have to decorate your web api action method with ResponseType tags as shown below.
Just to add to the fun , you can add that extra user friendly documentation by adding a sample request json for your request uri.For example most of the POST action methods in an api, can be a little tricky if you dont set the mandatory properties properly.You will however need to implement a small interface called ISchemaFilter as follows.You will need to set your sample json to @default property.
public class CustomerDefault : ISchemaFilter
{
public void Apply(Schema schema, SchemaRegistry schemaRegistry, System.Type type)
{
schema.@default = new { Age = "34", Name = "John", Address = "PO Box 565,24th Down Street,Newcastle" };
}
}
Finally just decorate your class with the SwaggerSchemaFilter tag as shown below
[SwaggerSchemaFilter(typeof(AssignDPCIInfoDefault))]
Thats it you will get a sample json request under the webapi method, once you fire up your swagger ui.
There are loads of customization that you can do via swagger.I would encourage to visit the below url at your leisure
Joshy's Blog 