Post
Ask Question

Swashbuckle Swagger Integration In WebApi 2

Introduction

In this article, you can see an integration of Swagger in WebApi2. Swashbuckle/Swagger is simple and powerful representation of any RESTful Web API. Swagger is and simple works as client to call Restfull Web API with an Application. There is no need to use other third party testing tool (Postman, Fiddler etc.). You can see in the list, given below-
  • What is Swashbuckle/Swagger ?
  • How to integrate Swagger with WebApi in MVC? 
  • How to use swagger in Web Application?
  • How to customize Swagger?
  • End point representation in Swagger UI.
  • Advantage of Swagger.
What is washbuckle/Swagger?

Swagger is an advance technique to represent RESTfull Web API. Swagger is working with an Application. You can configure Swagger inside your Application. Its very easy to use and integrate inside your MVC WebAPI project.

Technically, we can say, Swagger is a formal specification, which is  surrounded by a large ecosystem of tools, which includes each and everything from the front-end user interfaces. This is having low-level code libraries and commercial API management solutions.
 
How to integrate with WebAPI in MVC?

If you are going to integrate Swagger to test WebAPI in MVC Application, follow some steps, which are given below-
 
Step 1- Create a MVC Application, using Visual Studio (2012-latest version). I am giving to you an example, which is created on Visual Studio 2012 4.5. See the image, given below-

 

In this, I am creating a MVC 4 Application, select and type your project name and click "OK".
 
Step 2- After clicking "OK", you can see the screen, which is given below-
 


In this image, you can see two "controller" and "App_start", created by default. In this image, there are two controllers "Home" is its normal MVC controller and second is "value", which is Apicontroller. Swagger doesn't list the normal controller.
 
Step 3- Go your Application "SwaggerTesting"=>Right click=>click on "Manage NuGet Packages". Thereafter, you can see a screen. See the image, given below-

 

After this screen, type "swagger" in search textbox=>click install and you should wait for 1 minute, because it will take approximate 30 sec-1 minute.
 
Or 
 
Go to "TOOLS" menu on the top of the screen=>Library package manager=>Package manager console. Afterwards, this will open new Window on bottom of the editor.
 
PM>Install-Package Swashbuckle -Version 5.4.0 

Afterwards, swagger.config file will add automatically in your App_Start folder. See the image, given below-



You can see swagger.config file is added in App_start folder. Now, you are ready to use Swagger in your Application. There is no need to do any custom configuration, as it is by default and you can use.
 
How to use Swagger ?

Swagger works same as Web Application. You can run same as well as MVC controller, action and view. I am going to explain, how to use Swagger.
 
Step 4- Run your Application without any customization in the Application. See the image, given below-
 


After running the Application, the default page will open via this end point "http://localhost:10832/". To use Swagger, type "/swagger" and click enter. Your end point("http://localhost:10832/swagger") will open a new UI page. As per the image, you can see an example-
 
 

This is Swagger UI page. You can see here "swaggerTesting" is a header text. You can customize it, as per you requirement.

In this, you can see Swagger is listed in only API controller and not the simple controller. Click "Value" row and you can see each action with the header, parameter, action name, GET, POST etc.
  
Step 5-Click "Value"=>Expand all API list with the request method.
 
 
 
You can see all API list. According to HTTP method, colour is different. Now, click any and test to show the output. See the image, given below,
 
 

Step 6- Now, click any Web API and you can see all the details of Web API. Afterwards, set the parameter and click "Try it out".
The output will be shown at the bottom of the screen.
 
Customization of swagger.config

Customization of Swagger means Show API details from XML content, change the layout. Now, I am going to explain, how to show the details of each API on Swagger UI page. i am going to change swagger.config file to display API details on the right corner of the screen.
 
Step 7-Go to Application=>right click=>property=>select Build=>check "xml document file" to enable get XML content. See the image, given below,
 


In this image, you can see, I have checked on the checkbox to enable XML document. Also, i have added one more fresh APIController. 
  1. using System;  
  2. using System.Collections.Generic;  
  3. using System.Linq;  
  4. using System.Net;  
  5. using System.Net.Http;  
  6. using System.Web.Http;  
  7. using SwaggerTesting.Models;  
  8.   
  9. namespace SwaggerTesting.Controllers  
  10. {  
  11.     public class SwaggerTestController : ApiController  
  12.     {  
  13.         /// <summary>  
  14.         /// get simple string   
  15.         /// </summary>  
  16.           
  17.         [HttpGet]  
  18.         public string ResultGet()  
  19.         {  
  20.             return "swagger testing for get";  
  21.         }  
  22.         /// <summary>  
  23.         /// Post simple string   
  24.         /// </summary>  
  25.           
  26.         [HttpPost]  
  27.         public string ResultPost()  
  28.         {  
  29.             return "swagger testing for post";  
  30.         }  
  31.         /// <summary>  
  32.         /// To Update databse using EmpId  
  33.         /// </summary>  
  34.         /// <param name="EmpId"></param>  
  35.         [HttpPut]  
  36.         public string UpdateEmployee(Employee Emp)  
  37.         {     
  38.             /////////type code according your application  
  39.   
  40.             return "data Updated";  
  41.         }  
  42.     }  
  43. }  
In this, you can see, I have used <summary> tag, which represents the details of API on Swagger page. 
 
Step 8- After completing that step, go on Swagger. Config file creates new method to get XML document like-
  1. protected static string GetXmlCommentsPath()  
  2.         {  
  3.             return Path.Combine(System.Web.HttpRuntime.AppDomainAppPath, "bin", "SwaggerTesting.XML");  
  4.         }  
Uncomment "c.IncludeXmlComments(GetXmlCommentsPath());" this line of code.
 
End point representation in swagger UI

It means you see whole details of endpoint, using Swagger. See the image, which is given below,

like this "/api/swaggertest" with get method. 
 
Step 9- Run again and follow the previous step to open Swagger UI. Just type "/swagger" in the URL and see the image, given below-
 


In this image, you can see new controller, which i have created with the details on the right corner.
 
Step 10- Click any to set the parameter and click "try it out". It will return an output. See the image, given below-
 


You can understand more and see the image, given below,
 
Advantages of Swagger
  1. End point user standing about Web API.
  2. No need to add any extra configuration.
  3. This can integrate easily with the Application.
  4. No need to use other resources like POSTMAN etc. 
  5. Easy to understand parameter, model, datatypes, header to anyone. 
Conclusion

In this article, I explained about Swagger. I hope, you understood it. Actually, I am creating a dummy Application. Thus, you need to use routing, but if you are going to create Web API, which is set the route for each Web API.


Similar Articles