OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1

Introduction

 
This article demonstrates how to include NSwag to your project, so that you can execute and see your web api method results in Json format.
 
Before we get into NSwag, we have to see what is OpenAPI and Swagger.
 

OpenAPI Specification

 
OpenAPI Specification (earlier name was Swagger Specification) is an API description format for REST APIs. This file is used to describe our entire API, including available endpoints ( /users ) and action methods on each endpoint.
 
Now What is Swagger?
 
Swagger is a set of open-source tools built with OpenAPI Specification that can help you to document and consume REST APIs.
 

What is NSwag?

 
NSwag is a Swagger/OpenAPI tool for .NET Core and other platforms written in C#.
 
Now we can get into how to add NSwag to our project.
 
Step 1
 
Create a new project and configure it.
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 2
 
Select the .Net framework version and .Net Core version and choose as a API project (Here I took an API project for an example).
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 3
 
Your new project has been created with default settings and packages.
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 4
 
Run the application and confirm.
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 5
 
Right Click the project --> Manage NuGet Packages
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 6
 
Select Browse --> Type NSwag.AspNetCore --> Install
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 7
 
Confirmation pop up for dependency packages will be installed.
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 8
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 9
 
If you check the packages folder now, NSwag has ben installed.
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1

Step 10
 
This is the important setting to enable NSwag
  1. Register your Swagger Service under ConfigureServices method in Startup.cs
  2. Add Swagger generator under Configure method in in Startup.cs
    1. using System;      
    2. using System.Collections.Generic;      
    3. using System.Linq;      
    4. using System.Threading.Tasks;      
    5. using Microsoft.AspNetCore.Builder;      
    6. using Microsoft.AspNetCore.Hosting;      
    7. using Microsoft.AspNetCore.HttpsPolicy;      
    8. using Microsoft.AspNetCore.Mvc;      
    9. using Microsoft.Extensions.Configuration;      
    10. using Microsoft.Extensions.DependencyInjection;      
    11. using Microsoft.Extensions.Logging;      
    12. using Microsoft.Extensions.Options;      
    13.       
    14. namespace NSwag      
    15. {      
    16.     public class Startup      
    17.     {      
    18.         public Startup(IConfiguration configuration)      
    19.         {      
    20.             Configuration = configuration;      
    21.         }      
    22.       
    23.         public IConfiguration Configuration { get; }      
    24.       
    25.         // This method gets called by the runtime. Use this method to add services to the container.      
    26.         public void ConfigureServices(IServiceCollection services)      
    27.         {      
    28.             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);      
    29.       
    30.             //Register the Swagger services      
    31.             services.AddOpenApiDocument(c =>      
    32.             {      
    33.                 c.Title = "My API";      
    34.             });      
    35.         }      
    36.       
    37.         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.      
    38.         public void Configure(IApplicationBuilder app, IHostingEnvironment env)      
    39.         {      
    40.             if (env.IsDevelopment())      
    41.             {      
    42.                 app.UseDeveloperExceptionPage();      
    43.             }      
    44.             else      
    45.             {      
    46.                 app.UseHsts();      
    47.             }      
    48.       
    49.             app.UseHttpsRedirection();      
    50.             app.UseMvc();      
    51.       
    52.             //Register the Swagger generator      
    53.             app.UseOpenApi();      
    54.             app.UseSwaggerUi3();      
    55.         }      
    56.     }      
    57. }   
Step 11
 
Now set the startup method when we run the application.
 
Right click the project --> Click Properties
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Choose Debug and Change the Launch browser from api/values to swagger
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 
Step 12
 
Run the application. Your swagger tool is ready.
 
OpenAPI/ Swagger Using NSwag And ASP.NET Core 2.1
 

Summary

 
In this article, we have seen what NSwag is and how to install it  in your project.