Create a .NET Core API Documentation Representation using Swagger

This is a walk-through article by one of ClinkIT Solutions’ software developers providing the steps on how to use Swagger for .NET Core API Documentation Representation.

Being a back-end developer means setting up the backbone, making a high-level architectural plan, dealing with the server side of the application to make different platform types function as intended. There’s more about the role that I didn’t mention, and one of them is creating documentation which we, developers, commonly dislike. Maintaining them as part of your evolving application takes a lot of time that could have been used for working on more features.

Understanding a Web API’s various methods can be challenging for a developer. Swagger, also known as OpenAPI, can generate useful documentation and help pages for Web APIs. This addresses a lot of problems and saves us time. In this article, we will be setting up and implement Swashbuckle.AspNetCore which is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

Let’s Begin!

What we have below is a simple To-do API that is using ASP.NET Core 3.1. Our To-do Controller that has,
API
get all To-dos,
swagger
get a To-do,
swagger
update a To-do,
swagger
and lastly, delete a To-do.
swagger
Simply put, the codes above are the following endpoints or API calls that will be represented in our Swagger UI later:

Method

Route

Description

Parameter

Request Body

Response Body

GET
/api/todos
Get All to-do items
None
None
List of to-do items
GET
/api/todos/{id}
Get an item by Id
Id of an item
To-do item
To-do item
POST

/api/todos

Add a new item
None
None
To-do item

PUT

/api/todos/{id}
Update an existing item
Id of an item
To-do item
None
DELETE
/api/todos/{id}
Delete an item
Id of an item
None
None

Installation

Let’s now install Swashbuckle.AspNetCore into our API project with NuGet Package Manager.

swagger

Implementation

Once installed, we need to register Swagger middleware in our Services. The highlighted lines of code below register Swagger generator and defines Swagger document.

swagger

app.UseSwagger() enables middleware to serve generated Swagger as a JSON endpoint and app.UseSwaggerUI() enables middleware to serve Swagger UI specifying the JSON endpoint.

swagger

Now that everything is in place. Let’s launch the app and we should now see the beautiful Swagger UI by navigating to http://localhost:/swagger.

Todo API

As you can see, Swagger UI represented the following Endpoints that we’ve listed in the table earlier together with their defined Parameter, Request Body, and Response.

OpenAPI recognized a Controller class with [ApiController] attribute together with its valid Route that doesn’t have a conflict with other controllers. Same goes for Actions and Routes inside the Controllers, everything should be defined clearly, or else Swagger UI will not load correctly.

We can also use Swagger UI to test out API Calls by clicking the “Try it out” button and filling in predefined Parameters and Request Body. Check the Response right after executing it.

Clink Code

Now, we won’t have to spend so much time on maintaining documentation, since it is already reflected in the API definitions as we add new features. We can also use it as a well-presented documentation that other developers, project managers, and clients can play around with.

Get the latest insights on developer best practices, technologies and solutions for businesses here. Need help with application development or other development services? Schedule a free consultation with us.