Swagger - Aprimorando a documentação com anotações

Swagger - Aprimorando a documentação com anotações - II

Hoje veremos como incrementar a documentação do Swagger usando anotações na ASP .NET Core.

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:

Temos assim uma forma bem simples de incluir documentação sem usar arquivos XML.

Pegue o projeto aqui: DemoSwagger2.zip (sem as referências)

"Meus filhinhos, escrevo-lhes estas coisas para que vocês não pequem. Se, porém, alguém pecar, temos um intercessor junto ao Pai, Jesus Cristo, o Justo."
1 João 2:1

Referências:

José Carlos Macoratti