.Net Core API With Swagger Documentation

In this blog I am sharing my experience in creating swagger documentation for our .Net core Api.

In this blog I am going to explain how to add Swagger documentation to our .Net Core Web api application. 

 

What is SwaggerUI

 

Swagger-UI is an open source tool to generate the documentation for our Api project based on specification. Here we can able to configure the input and output for our Api’s and its very convenient to use instead of Postman.

 

This blog divided into the following section,

1. Creating .Net core web api Project
2. Adding Swagger for Documentation

Creating .Net core Web Api Project. 

 

 

 

 

Here I am using Visual studio 2019 and .Net Core framework 3.1

 

Adding New Controller

 

Here I am adding new Api controller to our application.

 

 

 

Model Class

 

Creating model class for sample input and outputs.

 

 

 

Controller Action methods

 

Action methods are most important one for our documentation. It will create the UI documentation based on the Http Verbs and attributes.

 

 

 

Adding Swagger

 

To add Swagger to our application we need to install Swashbuckle.AspNetCore package from Nuget package manager.

 

 

 

Add the below set of lines in Startup.cs file for Api versioning and swagger api endpoint configuration.

 

 

 

Change the launch Url in launchSettings.json (swagger/index.html is default url for swagger-UI documentation)

 

 

 

Run the application to view the basic Swagger documentation.

 

 

 

XML Documentation

 

Until now we have done all the changes for basic swagger documentation. But if we need to add more details on our documentation(Ex : display short definition of our API ), we need to do the below changes on our application.

 

Configure XML documentation to add summary and input for each action.

 

 

 

 

 

Display your Sample Response

 

If we want to show our sample response in our swagger documentation add the [ProducesResponseType] attributed and mention your return type as shown below.