Continuing the first part of the article, we will now see how to generate the documentation without having to generate 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 DemoSwagger2Using 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.AnnotationsNext, 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 PI 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 include 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)
*The content of this article is the author’s responsibility and does not necessarily reflect the opinion of iMasters.
Leave a comment