.NET Web API Documentation Using Swagger or Doc Template
Shehryar Khan
Shehryar Khan
March 13, 2022
2 min

Table Of Contents

Why API Documentation is Important?
Auto-Generated API Documentation Vs Manual
Swagger Implementation
Creating Project


One of the most common habits in most of the programmers I have seen in my programming carrier is that they hate to document their code. Programmers find it easier to solve a complex mathematical problem or implement a shortest distance algorithm instead of documenting something. That’s one of the reasons that libraries for automatically generating API documentation are now considered as the necessary part of any Web API project.

Gerald Weinberg, the father of the psychology of programming said it well:

swagger 1

In this article, we’ll see what choices are available for automatically generating API documentation or manually document the APIs & which is more simpler. Before that, we must have a clear idea about the importance of API Documentation.

Why API Documentation is Important?

For understanding the importance of API Documentation, we should be aware of the purpose of APIs. Let’s take an example of FaceBook, which has a Web as well as a Mobile Application for its Users. Facebook keeps Its data in a central server, whether you are using your Facebook Account from a browser on your Desktop or in your Smartphone Application. So, API(Application Programming Interface) do this job to retrieve or push data on a central server.

It means that APIs can be integrated by the web & mobile application developers. That’s the reason that we need to provide APIs documentation to Applications developers like what method is API will use, its parameters & response.

Auto-Generated API Documentation Vs Manual

Yes, programmers community doesn’t like to write documentation that’s one of the reasons why Swagger, also known as OpenAPI is as popular as it’s seems to be a part of every API project. It not only automatically generates interactive documentation, also provides an interface to quickly test the APIs.

The other way to document the APIs is to create a shared document where you can manually add your APIs details so a developer, who wants to consume API, can understand the request & response structure. I’ll share Google Docs Template for this purpose but first, let’s see how can we implement Swagger by Swashbuckle for Auto generated APIs documentation.

Swagger Implementation

Swashbuckle Nuget Package is also available for .Net Core. So, we can easily use Swagger in our .Net Core APIs project.

Creating Project

Let’s start by creating a new .Net Core API Project using dotnet core cli.

dotnet new webapi

after running the above command we have a project with a Controller as ValuesController.cs

swagger 2

Now, we need to install the Swagger Nuget Package for Asp.Net Core.

I’m again using dotnet core cli to do this job, here’s the command which will install the latest stable version

dotnet add package Swashbuckle.AspNetCore

Open Startup.cs file & Add the below code in your ConfigureServices Method after services.AddMvc()

services.AddSwaggerGen(c =>
    c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

Import the reference automatically or like this using Swashbuckle.AspNetCore.Swagger;

Now, add the below code inside your Configure Method of your Startup.cs class.

app.UseSwaggerUI(c =>
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

Run your project & go to this URL:


Your URL might be a little different or have a different port.

You’ll see Swagger UI with all your APIs in ValuesController

swagger 3

Manual API Documentation Template

We can also use this Doc Template as API Specification Document. There are many Great templates are available, I’m also gonna share an interactive template to Document APIs.

Here’s an example of a single API detail.

swagger 4 I’m considering that the above Example is self-explanatory & I don’t have any need to explain how to use this template. So, here’s the link for the template.

Go to File menu & click on Make a Copy & enjoy developing APIs.

Thank you for reading this article, comment below If you need any kind of help in your .Net Core Application Development. I’m always available to help you.

Related Articles:

JWT Authentication Configuration in .Net 7

.Net Web Api multipart/form-data – upload File with Form Data


Shehryar Khan

Shehryar Khan

Full-Stack .NET Developer

I'm passionate about learning new technologies as well as mentoring and helping others get started with their programming career. This blog is my way of giving back to the Community.



Social Media


Related Posts

Let’s Ready a .Net Core Web API Project
April 03, 2022
3 min
© 2023, All Rights Reserved.

Quick Links

Advertise with usContact Us

Social Media