Web API Documentation Using Swagger or Doc Template

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:

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.

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

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.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

Run your project & go to this URL:

https://localhost:5001/swagger

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

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

Manual API Documentation Template

We can also use any 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.

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.

API Specification DoC

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.

Here’re some more related articles:

– HOW TO CREATE SOAP WEB SERVICES IN DOTNET CORE