Como incrementar a documentação do Swagger usando anotações na ASP .NET Core (parte 2)

Continuando a primeira parte do artigo veremos agora como gerar a documentação sem precisar gerar o arquivo XML. Vamos criar um novo projeto Web API chamado DemoSeagger2 usando as mesmas configurações do artigo anterior.

Isso pode ser feito no Visual Studio 2022 ou usando o NET CLI com o VS Code através do comando :

dotnet new webapi -o DemoSwagger2

Usando anotações Swashbuckle

Vamos iniciar definindo a configuração habilitando as anotações sem incluir a referência ao arquivo xml.

Para poder realizar anotações vamos incluir em nosso projeto o pacote Swashbucle.AspNetCore.Annotations :

dotnet add package Swashbuckle.AspNetCore.Annotations

A seguir vamos habilitar no projeto o uso das anotações :

using Microsoft.OpenApi.Models;var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();

builder.Services.AddSwaggerGen(
c =>
{
c.EnableAnnotations();
c.SwaggerDoc(“v1”, new OpenApiInfo
{
Title = “Swagger Documentação Web API”,
Description = “Um exemplo de como fornecer a documentação para APIs.”,
Contact = new OpenApiContact() { Name = “Macoratti”, Email = “macoratti@yahoo.com” },
License = new OpenApiLicense() { Name = “MIT License”, Url = new Uri(“https://opensource.org/licenses/MIT”) }
});
}
);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

Agora vamos fornecer alguma documentação para a nossa API alterando o código do endpoint GetWeatherForecast do controlador usando o atributo SwaggerOperation conforme abaixo:

[HttpGet(Name = “GetWeatherForecast”)]
[SwaggerOperation(Summary =”Obtém a lista da previsão de tempo “)]
[ProducesResponseType(typeof(IEnumerable<WeatherForecast>),StatusCodes.Status200OK)]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}

Além disso podemos fornecer informações ao cliente da PI como os possíveis códigos de status HTTP e seu corpo de resposta. Para isso vamos usar o atributo SwaggerResponse e definir, a título de exemplo que o endpoint da API pode retornar seus cinco códigos de status HTTP possíveis (200, 400, 409, 500 e 503).

        [HttpGet(Name = “GetWeatherForecast”)]
[SwaggerOperation(Summary =”Obtém a lista da previsão de tempo “)]
      [SwaggerResponse(StatusCodes.Status200OK, Type = typeof(IEnumerable<WeatherForecast>))]
[SwaggerResponse(StatusCodes.Status400BadRequest)]
[SwaggerResponse(StatusCodes.Status409Conflict)]
[SwaggerResponse(StatusCodes.Status500InternalServerError)]
[SwaggerResponse(StatusCodes.Status503ServiceUnavailable)]
        public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}

A seguir vamos incluir uma documentação na classe WeatherForecast usada como modelo de domínio no projeto usando o atributo SwaggerSchema :

using Swashbuckle.AspNetCore.Annotations;
namespace DemoSwagger2;

public class WeatherForecast
{
[SwaggerSchema(Description = “Data e hora para a previsão”)]
public DateTime Date { get; set; } [SwaggerSchema(Description = “Temperatura em Celsius”)]
public int TemperatureC { get; set; }

[SwaggerSchema(Description = “Temperatura em Fahrenheit”)]
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

[SwaggerSchema(Description = “Resumo da previsão”)]
public string? Summary { get; set; }
}

Podemos também definir os tipos de mídia de consumo e produção apropriados decorando o nosso controlador com os atributos [Consumes] e [Produces] definindo o valor application/json :

[ApiController]
[Route(“[controller]”)]
[Consumes(“application/json”)]
[Produces(“application/json”)]
public class WeatherForecastController : ControllerBase
{
…
}

Agora vamos executar o nosso projeto e ver o resultado: