How to add Swagger in Web API

Back to: ASP.NET Web API Tutorials For Beginners and Professionals

How to Add Swagger in Web API Application

In this article, I will discuss How to add Swagger in Web API Applications to document and test restful Web API services. Please read our previous article, where we discussed How to Create an ASP.NET Web API Application step by step before proceeding to this article, as we will work with the same example. As part of this article, we will discuss the following pointers.

1. What is Swagger?
2. How to Add Swagger to Web API Application?
3. How to Configure Swagger in ASP.NET Web API?
4. Understanding the Swagger UI.
5. How to enable Swagger to use XML comments?

What is Swagger?

The Swagger is a simple but powerful representation of the RESTful API. Nowadays, most developers use Swagger in almost every modern programming language and deployment environment to document. With a Swagger-enabled Web API, you will get interactive documentation, client SDK generation, and discoverability.

How to Add Swagger to Web API Project?

To add Swagger to your ASP.NET Web API project, you need to install an open-source project called Swashbuckle via NuGet, as shown below.

Once the package is installed successfully, navigate to the App_Start folder in Solution Explorer. You will find a new file called SwaggerConfig.cs. This is the file where Swagger is enabled, and any configuration options should be set here.

How to Configure Swagger in ASP.NET Web API Application?

To enable Swagger and Swagger UI, modify the SwaggerConfig class as shown below.

namespace FirstWebAPIDemo
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;
            GlobalConfiguration.Configuration
              .EnableSwagger(c => c.SingleApiVersion("v1", "First WEB API Demo"))
              .EnableSwaggerUi(); 
        }
    }
}

Start a new debugging session by pressing the F5 key and navigating to http://localhost:[PORT_NUM]/swagger, and then you should see the help pages for your APIs.

Ok. That’s cool. Now expand an API and then click on the “Try it out!” button, which will make a call to that specific API and return results as shown in the below image.

Here, click on the Try it out Button, which will display the result below.

In the same way, you can test all other methods.

How to enable Swagger to use XML Comments in ASP.NET Web API Application?

As of now, we use the minimum configuration to get started. But now we are going to add more customization. We can tell the Swashbuckle to use our custom XML comments to add more details about our APIs to the Swagger metadata.

First, we need to enable XML documentation file creation during the build. In the Solution Explorer, right-click on the Web API project and click on the Properties. Click the Build tab and navigate to Output. Make sure the XML documentation file is checked. You can leave the default file path. In our case it bin\FirstWebAPIDemo.XML as shown below

Next, we must tell the Swashbuckle to include our XML comments in the Swagger metadata. To do this, we must add the following line to SwaggerConfig.cs. Make sure to change the file path to the path of your XML documentation file.

c.IncludeXmlComments(string.Format(@”{0}\bin\FirstWebAPIDemo.XML”, System.AppDomain.CurrentDomain.BaseDirectory));

Configuration, so far

namespace FirstWebAPIDemo
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
              .EnableSwagger(c =>
              {
                  c.SingleApiVersion("v1", "First WEB API Demo");
                  c.IncludeXmlComments(string.Format(@"{0}\bin\FirstWebAPIDemo.XML",
                                       System.AppDomain.CurrentDomain.BaseDirectory));
              })
              .EnableSwaggerUi();
        }
    }
}

Let’s add some XML documents to our API methods, as shown below. Here, we are adding an XML Document to the get method. Modify the Get method as shown below.

/// <summary>
/// Get All the Values
/// </summary>
/// <remarks>
/// Get All the String Values
/// </remarks>
/// <returns></returns>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

Run the application and navigate back to /swagger. You should see more details added to your API documentation, as shown below.

In the next article, I will discuss Using Fiddler to Test ASP.NET Web API Services. Here, in this article, I try to explain how to add Swagger in Web API Application to document and test ASP.NET Web API Services. I hope now you have a good understanding of how to use Swagger in ASP.NET Web API Applications.