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).

Step 3

Your new project has been created with default settings and packages.

Step 4

Run the application and confirm.

Step 5

Right Click the project --> Manage NuGet Packages

Step 6

Select Browse --> Type NSwag.AspNetCore --> Install

Step 7

Confirmation pop up for dependency packages will be installed.

Step 8

Step 9

If you check the packages folder now, NSwag has ben installed.

Step 10

This is the important setting to enable NSwag

Register your Swagger Service under ConfigureServices method in Startup.cs
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;
14. namespace NSwag
15. {
16. public class Startup
17. {
18. public Startup(IConfiguration configuration)
19. {
20. Configuration = configuration;
21. }
23. public IConfiguration Configuration { get; }
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);
30. //Register the Swagger services
31. services.AddOpenApiDocument(c =>
32. {
33. c.Title = "My API";
34. });
35. }
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. }
49. app.UseHttpsRedirection();
50. app.UseMvc();
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

Choose Debug and Change the Launch browser from api/values to swagger

Step 12

Run the application. Your swagger tool is ready.

Summary

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