Swagger API Documentation Tool

Serkan

0 2 minutes read

Contents

Do you need documentation showing how developers and customers will use web API projects? And you think how to document your API. Don’t worry, there are several tools that do this. The most preferred of these is the Swagger Documentation Tool. At the end of this post, you will be able to document your API and present it to the end user.

In this post, I will document the web API project we created earlier. If you do not have a web API project, read the Create And Consume ASP.NET Core Web API to create a Web API.

What is Swagger?

Developed by SmartBear to better implement and visualize APIs. They define themselves as follows:

Swagger is a set of rules (in other words, a specification) for a format describing REST APIs. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools to automate API-related processes.

Download NSwag.AspNetCore NuGet Package

Right-click the existing API project and click the Manage NuGet package option. For Core based projects, search and download the NSwag.AspNetCore plugin here. Or you can install it by typing the following line into Package Manager Console.

Install-Package NSwag.AspNetCore -Version 13.8.2

Configure Swagger Middleware

After loading the plugin to the project, we must declare the Swagger document in the ConfigureServices and Configure methods in the Startup.cs class.

Add the following line to the ConfigureServices method of the Startup.cs class. This code registers the plugin’s services.

services.AddSwaggerDocument();

And, add the following lines to enable middleware to provide Swagger features and user interface in Configure method.

app.UseOpenApi();
app.UseSwaggerUi3();

Run the application and go to http://localhost:<port>/swagger to view the interface. Also, go to http://localhost:<port>/swagger/v1/swagger.json to view properties.

Test Methods in Swagger

Let me try the Users Controllers’ GET method as an example. Click on the try it out button and enter the id parameter. Then click on execute.

This is our result. You can also download the response body as JSON file.

Add Description to Methods

We can write a summary on the methods in the Controllers classes, explaining which methods will be used for what, which parameters will be taken to the user. Swagger will add these summaries as comments next to the methods. Let’s do an example.

First, write the required explanation in the summary tag above the method as below. Tip: Typing /// automatically opens the summary tab.

/// <summary>
/// Get All Users from database.
/// </summary>
/// <returns></returns>
// GET: api/Users
[HttpGet]
public async Task<ActionResult<IEnumerable<Users>>> GetUsers()
{   
    return await _context.Users.ToListAsync();
}

Then right click on the project and open the properties window. Then, activate the XML documentation file option from the Build tab.

Here now run the application.

API Info And Description

To add information such as author, license, version to the document, you can add the required information to the AddSwaggerDocument method in the Startup.ConfigureServices method.

            services.AddSwaggerDocument(config =>
            {
                config.PostProcess = (doc =>
                {
                    doc.Info.Version = "v2";
                    doc.Info.Title = "Palette Core API";
                    doc.Info.Contact = new NSwag.OpenApiContact()
                    {
                        Name = "Serkan",
                        Url = "https://www.serkanseker.com/",
                        Email = "info@serkanseker.com",
                    };
                });
            });

Here now run the application.

Conclusion

Documentation preparation process for Web API projects can be done easily with the help of Swagger. In addition, the response bodies of the tested queries can be downloaded in JSON format. That’s all from this post.