Add NSwag Documentation to ASP.NET Core Web API

Introduction

 

Today, I am continuing a new topic: NSwag documentation for Asp.net core API. NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for the Number of C# based platforms such as .NET, .NET Core, Web API, ASP.NET Core, TypeScript, and other platforms. The OpenAPI/Swagger specification uses JSON and JSON Schema to describe a RESTful web API. The NSwag project provides tools to generate OpenAPI specifications from existing and new ASP.NET Web API controllers and client code from these OpenAPI specifications. In this post, I will have focus at only generate OpenAPI(Swagger) documentation for ASP.Net Core web API. In my next post, I will have a detail description of the C# client code generation. Before moving forward regarding generating OpenAPI ( Swagger ) documentation for ASP.Net Core web API, OpenAPI Specification needs to be understood.

 

OpenAPI Specification ( aka Swagger Specification) is an API description format of any REST APIs. An OpenAPI file allows you to describe your entire API, including:

• Available endpoints i.e. (/users) and operations on each endpoint (GET /users, POST /users & PUT /user)
• Operation parameters Input and output for each operation
• Authentication methods
• Contact information, license, terms of use, and other information.

API specifications can be written in YAML or JSON format by us. This format is easy to learn and readable to both humans and machines.

 

In my previous post, we are aware of how we can build an ASP.Net core web API using EF core. The real challenge starts when we have created some Controller Class and those Action methods for performing Get, Post, Put, and Delete requests for the API. Now it becomes a deal of how to test all routes and endpoints of web API. We have to download and use several third-party tools like Postman to examine the API. But swagger Documentation makes this deal easy for you using a UI representation. Developers or Consumers can envision and interact with the API routes. These API endpoints can be tested easily without using any third-party tools. This swagger API UI represents the all endpoint as interactive API documentation that lets you try out the API calls directly in the browser.

 

This magic happens with NSwag. For the same, You can customize your ASP.Net core API to generate Swagger/OpenAPI Documentation with the following NSwag package ( NSwag.AspNetCore ). This NuGet package provides some extension methods to register the NSwag ASP.NET Core services and AspNetCore Middleware. This combination and a few configurations in Startup.cs file gives your ASP.Net core API a beautiful and interactive UI. This UI represents all of your API controllers that contain API actions for all HTTP verbs.

 

Let's write some stuff for Swagger/OpenAPI documentation generation. 

 

Step 1

 

Open Visual Studio 2019 on your computer.

 

Step 2

 

I hope you have a basic idea how to create an ASP.Net Core web API. If not, you can visit my previous post: build an ASP.Net core web API using the existing database.

 

You can also visit here, or you can open your existing ASP.Net Core web API in the visual studio.

 

Step 3

 

Now, select Manage NuGet Packages for your project.

 

 

Step 4

 

Now, search for NSwag.AspNetCore NuGet packages and install the stable version of NSwag.AspNetCore NuGet package.

 

 

Step 5

 

Its time to add the Swagger Magic in the API. Open your Startup.cs file and add the below lines into the ConfigureServices method.

services.AddSwaggerDocument(o => o.Title = "Core API");

Step 6

 

Now, add the below lines into the Configure method of the Startup.cs file

app.UseSwaggerUi3();
app.UseAuthorization();

Your startup.cs should have required NSwag Package provide the Extension methods calling.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<CoreDbContext>(op => op.UseSqlServer(Configuration.GetConnectionString("Database"))); //Add
        // Add your NSwag Extension here
        services.AddSwaggerDocument(o => o.Title = "My Awesome core API");
        //----
        services.AddControllers();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        app.UseHttpsRedirection();
        app.UseRouting();
        // Add your NSwag Extension here
        app.UseOpenApi();
        app.UseSwaggerUi3();
        // -------------------
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

Step 7

 

Now, select and open the properties of your project.

 

 

Step 8

 

Change the URL to "swagger" in the Debug properties of your project.

 

 

Step 9

 

All done now. Build and run your API.

 

 

Finally, we have learned how to use NSwag to generate Swagger( OpenAPI) documentation in this post. In my next post, generate client code Using the same core web API and NSwag Studio. Here is the link of my post for generate the C# Client code for ASP.Net Core API using NSwagStudio .