Adding Swagger to Existing .Net Core WEB API Project

In this article we will see How we can add Swagger to an existing WebAPI project.

First why we need swagger here in this case?

Unlike SAOP based web sevrices or WCF Services, WebAPI are RESTFul. That means there is no WSDL in WebAPI. So Unless you prepare proper documentation about the methods, parameters and outputs, its hard to any consumer of the service to interpret them.

This is where swagger comes into the picture. If you use swagger and SwaggerUI in your WebAPI project, it pretty much takes care of the documentation part. It not only gives you the complete details of methods, parameters and outputs of the sevice, but also provides a UI component where consumers can test the service, without any third party tools.

For this example, i am using WebAPI project from one of the course on Linkedin Learning.

Here is the link for you to download and try it for yourself.

Download it and open the project and run it.

You will see this. With out any documentation, how anyone could interpret this.

Lets start with the swagg.

Step 1: Open Existing WebAPI project in Visual studio. Go to Tools and open "Nuget Package Manager" and click on "Manage Nuget Packages for the Solution".

Now browse for "Swashbuckle.ASP.Net Core", install it by selecting the WebAPI project.

This will install both Swagger and Swagger UI refreneces in your project.

Step2: Open Startup.cs file. This file handles all the regsitration of the controllers we use in WebAPI and the request pipelines. If you read default comments provided by framework itself, you will understand. 

There are 2 methods in that file.

1. ConfigureServices(): This is where you need to register all the controllers you expose in your service.

2. Configure(): This is where you will register request pipeline like handlers,authorization and routing.

Add assembly reference of "Microsoft.OpenAPI.Models" 

Add below code in ConfigureServices() method.

services.AddSwaggerGen(c=> {
     c.SwaggerDoc("v1", new OpenApiInfo { 
                            Title="HPlus Sports",
                            Version="1.0",
                            Description="Product API for HPlus Sports."                   
                });
            });

 Add below code in Configure() method.

app.UseSwagger();
app.UseSwaggerUI(c=> {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "HPlus Sports");
            });

With this we requested to generate SwaggerDoc and also regietred it with endpoint "/swagger/v1/swagger.json".

Also we requested SwaggerUI to use the above endpoint for its testing purpose.

Step 3: Lets build the solution and test it.

Run the project and you will see this as earlier.

 

Now change the url form "https://localhost:44321/api/product" to "https://localhost:44321/swagger/v1/swagger.json" and you see the json of the service revealing all the details required for invoking methods with proper parameters.

On top of this if you change the url to "https://localhost:44321/swagger/index.html", Service consumers can access SwaggerUI to run tests on the service to understand the output of the service calls, without using any third party tools. 

let me know if it helps. Thank you.