Test Your ASP.NET Core Web API With Swagger

PM> Install-Package Swashbuckle.AspNetCore

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });
    });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseHsts();
    }

    app.UseHttpsRedirection();

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1.0/swagger.json", "My Demo API (V 1.0)");
    });
    app.UseMvc();
}

When we run the application, we can see the following Swagger UI for ValuesContoller.

As we see here, it uses a different color code for each HTTP verb. When we click on any action method it will ask for parameter details and when we click on the execute button it will send a request to the web API.

The Swagger requires minimum configuration to test our web API. It also shows XML comments when generating UI but that requires some configuration.

The .net /.net core framework provides a way to write XML comments for the documentation. In .net core, we can enable XML comments by setting up the "XML documentation file" property under the build tab of project property windows.

Swagger UI does not show this documentation by default. We need to pass the path to IncludeXMLComments.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });
        c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "SwaggerDemo.xml"));
    });
}

Configure Swagger in ASP.net Core Web API using NSwag

Following are the steps to configure Swagger in ASP.net Core Web API using NSwag.AspNetCore.

Step 1. Install-Package NSwag.AspNetCore

Using the following command, we can install a package of NSwag.AspNetCore.

PM> Install-Package NSwag.AspNetCore

Step 2. Configure Swagger middleware

To add a Swagger middle to the request pipeline, we need to theSwaggerDocument method in the ConfigureService method of the startup class. This method adds a default document with the name "V1". If we want to add more than one document, call this method multiple times with a different document name.

Startup. cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddSwaggerDocument();
}

If want to enable this middleware, we need to call the UseSwagger method in the configure method of the startup class. This method adds the default route as "/swagger/{documentName}/swagger.json" Also we need to call the UseSwaggerUi3 method to add the Swagger UI to the request pipeline.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseHsts();
    }

    app.UseHttpsRedirection();

    app.UseSwagger();
    app.UseSwaggerUi3();

    app.UseMvc();
}

The above steps are required to set up Swagger. If we want to launch Swagger in a development environment using Visual Studio, one more change is required. To set Swagger UI, go to the project property - debug tab and change Launch Browser value to "swagger".

Summary

Swagger helps us to test our web API without any third-party tool and custom code. In this article, I have explained how to configure Swagger using Swashbuckle and NSwag.

You can view or download the source code from the GitHub link here.