.Net Core API With Swagger Documentation

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,

Creating .Net core web api Project
Adding Swagger for Documentation

Creating .Net core Web Api Project.

.Net core Api with Swagger documentation

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.