Swagger UI Integration With Web API For Testing And Documentation

Add Controller with read and write access.

using System;  
using System.Collections.Generic;  
using System.Data;  
using System.Data.Entity;  
using System.Data.Entity.Infrastructure;  
using System.Linq;  
using System.Net;  
using System.Net.Http;  
using System.Web.Http;  
using System.Web.Http.Description;  
using SwaggerIntegrationDemo.Models;  
  
namespace SwaggerIntegrationDemo.Controllers  
{  
    public class EmployeesController : ApiController  
    {  
        private SwaggerIntegrationDemoContext db = new SwaggerIntegrationDemoContext();  
  
  
        // GET: api/Employees  
  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        /// <summary>   Gets the employees. </summary>  
        ///  
        /// <remarks> List of all employees </remarks>  
        ///  
        /// <returns>   The employees. </returns>  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
  
        public IQueryable<Employee> GetEmployees()  
        {  
            return db.Employees;  
        }  
  
        // GET: api/Employees/5  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        /// <summary>Get Employee by Id. </summary>  
        ///  
        /// <remarks> Employee Details for Requested employeId </remarks>  
        ///  
        /// <returns>Returns Employee object </returns>  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        [ResponseType(typeof(Employee))]  
        public IHttpActionResult GetEmployee(int id)  
        {  
            Employee employee = db.Employees.Find(id);  
            if (employee == null)  
            {  
                return NotFound();  
            }  
  
            return Ok(employee);  
        }  
  
        // POST: api/Employees  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        /// <summary>Create New Employee </summary>  
        ///  
        /// <remarks> Creates new employee using PostEmployee method </remarks>  
        ///  
        /// <returns></returns>  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        [ResponseType(typeof(Employee))]  
        public IHttpActionResult PostEmployee(Employee employee)  
        {  
            if (!ModelState.IsValid)  
            {  
                return BadRequest(ModelState);  
            }  
  
            db.Employees.Add(employee);  
            db.SaveChanges();  
  
            return CreatedAtRoute("DefaultApi", new { id = employee.EmployeeId }, employee);  
        }  
  
        // DELETE: api/Employees/5  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        /// <summary>Delete Existing Employee By Id </summary>  
        ///  
        /// <remarks> Delete requested employee </remarks>  
        ///  
        /// <returns></returns>  
        ////////////////////////////////////////////////////////////////////////////////////////////////////  
        [ResponseType(typeof(Employee))]  
        public IHttpActionResult DeleteEmployee(int id)  
        {  
            Employee employee = db.Employees.Find(id);  
            if (employee == null)  
            {  
                return NotFound();  
            }  
  
            db.Employees.Remove(employee);  
            db.SaveChanges();  
  
            return Ok(employee);  
        }  
  
        protected override void Dispose(bool disposing)  
        {  
            if (disposing)  
            {  
                db.Dispose();  
            }  
            base.Dispose(disposing);  
        }  
  
        private bool EmployeeExists(int id)  
        {  
            return db.Employees.Count(e => e.EmployeeId == id) > 0;  
        }  
    }  
}

Step 4 - Add Swashbuckle from NuGet packages

Go to solution and select "Manage NuGet Packages" and search for Swashbuckle to install it. It will integrate swagger to our application.

using System.Web.Http;  
using WebActivatorEx;  
using SwaggerIntegrationDemo;  
using Swashbuckle.Application;  
  
[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]  
  
namespace SwaggerIntegrationDemo  
{  
    public class SwaggerConfig  
    {  
        public static void Register()  
        {  
            var thisAssembly = typeof(SwaggerConfig).Assembly;  
  
            GlobalConfiguration.Configuration  
                .EnableSwagger(c =>  
                 {  
                         
                        c.SingleApiVersion("v1", "Documentation Using Swagger UI");  
  
                       // c.IncludeXmlComments(string.Format(@"{0}\bin\SwaggerIntegrationDemo.xml", System.AppDomain.CurrentDomain.BaseDirectory));                      
                 })  
                .EnableSwaggerUi(c =>  
                 {  
                        c.DocumentTitle("Employee Swagger UI");  
                  });  
        }  
    }  
}

We are done with all required action. Just need to build a solution and it will open with default page of our application.

Let’s do testing for all API methods using Swagger UI. First, we will create a new employee and then we will retrieve the same employee. Look at the below two snippets,

In first and second snippet I have created the new employee with first name Jaydeep and last name with Patel and city as Rajkot. We able to see at down status code 201 which mean it created a new record with employee id 4 on the server.

In the third snippet, I had tried to fetch the same record with Employee id as 4 and the same employee shown as json response body with response code 200.

Let’s test the Employees Get API method. Click on Try it out button and you will be able to see the list of all employees which we had created using Post method.

Like Post and Get employee, we can test all API methods using swagger UI.

If we want to enable documentation for the API method, then follow the below steps.

Step 1

Go to solution build property and check the checkbox for XML documentation file.

// GET: api/Employees   
////////////////////////////////////////////////////////////////////////////////////////////////////    
/// <summary>   Gets the employees. </summary>    
///    
/// <remarks> List of all employees </remarks>    
///    
/// <returns>   The employees. </returns>    
////////////////////////////////////////////////////////////////////////////////////////////////////    

public IQueryable<Employee> GetEmployees()    
{    
    return db.Employees;    
}    

// GET: api/Employees/5    
////////////////////////////////////////////////////////////////////////////////////////////////////    
/// <summary>Get Employee by Id. </summary>    
///    
/// <remarks> Employee Details for Requested employeId </remarks>    
///    
/// <returns>Returns Employee object </returns>    
////////////////////////////////////////////////////////////////////////////////////////////////////    
[ResponseType(typeof(Employee))]    
public IHttpActionResult GetEmployee(int id)    
{    
    Employee employee = db.Employees.Find(id);    
    if (employee == null)    
    {    
        return NotFound();    
    }    

    return Ok(employee);    
}

Enable Documentation in SwaggerConfig.cs file and give XML file path using Includexmlcomments in swagger configuration file as per the below snippet.

Step 4

Look at the right side in swagger UI screen as below, you are able to comment which was provided in our employee controller API methods as XML styled comments.

In the below screen, I have pointed out which comment displayed where in swagger UI. This comment really helps the end user to identify which API action method is doing what by the right side of that operation.

Look in our example we are able to see “Get all the employees” at the right side, it says that this method fetches all employee records. At bit farther down it displayed that this method returns “List of all employees”. Click on Expand operation and you can check all XML styled comments are there with the respective operation.

At last, I want to point out a few reasons why we should use swagger,

1. It generates a UI for us to test API methods and it's easy to test bcause it will give an auto generated example of json to pass vaules for our method.
2. it eliminates need of other tools like Postman, Soap UI, fidler etc.

I hope you enjoyed this article.

If you want to refer my articles and blogs, please visit this link My Articles and blogs

Thank you for reading.