iMasters.com - Knowledge for Developers.
Follow Us
Home Backend Swagger – Improving documentation with annotations – II
Backend

Swagger – Improving documentation with annotations – II

Today we’ll look at how to spice up Swagger’s documentation using annotations in ASP .NET Core.

Continuing the first part of the article, we will now see how to generate the documentation without generating the XML file.

Let’s create a new Web API project called DemoSeagger2 using the same settings as in the previous article.

This can be done in Visual Studio 2022 or using the NET CLI with VS Code through the command:

dotnet new webapi -o DemoSwagger2

Using Swashbuckle annotations

Let’s start by setting the configuration enabling annotations without including the reference to the XML file.

To be able to take notes, let’s include the Swashbucle.AspNetCore.Annotations package in our project:

dotnet add package Swashbuckle.AspNetCore.Annotations

Next, let’s enable the use of annotations in the project:

Now let’s provide some documentation for our API by changing the controller’s GetWeatherForecast endpoint code using the SwaggerOperation attribute as below:

In addition, we can provide the API client with information such as possible HTTP status codes and their response body. For this, we will use the SwaggerResponse attribute and define, by way of example, that the API endpoint can return its five possible HTTP status codes (200, 400, 409, 500, and 503).

Next, let’s add documentation on the WeatherForecast class used as a domain model in the project using the SwaggerSchema attribute:

We can also define the appropriate consumption and production media types by decorating our controller with the [Consumes] and [Produces] attributes by setting the application/json value:

Now let’s run our project and see the result:

We thus have a simple way to include documentation without using XML files.

Get the project here: DemoSwagger2.zip (without references)

“My little children, I write these things to you so that you may not sin. But if anyone sins, we have an intercessor with the Father, Jesus Christ the righteous.”
1 John 2:1

*The content of this article is the author’s responsibility and does not necessarily reflect the opinion of iMasters.

Written by
Jose Carlos Macoratti

José Carlos is a reference in Visual Basic in Brazil, books author "Aprenda Rapid: ASP" and "ASP, ADO and Banco de Dados on the Internet", and maintainer of the macoratti.net website.

Leave a comment

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *

Related Articles

Backend

How to Create a Skill for Amazon’s Virtual Assistant Alexa

If you didn’t know, it is not necessary for an Amazon Echo...

Backend

The APIs role in a 5G world

5G is about to revolutionize how we connect and use technology daily....

Backend

EF Core using AsNoTracking with Identity Resolution

Today we will see the consequences of using AsNoTracking with the Identity...

Backend

Understand key features added in ASP.NET Core 7.0

Version 7.0 of the .NET platform brought many new features in this...