Swashbuckle para C# (.NET): guia completo com exemplos práticos

O que é Swashbuckle e por que usá-lo?

Swashbuckle é uma biblioteca poderosa para a plataforma .NET que gera automaticamente documentação interativa para suas Web APIs com base no padrão OpenAPI (anteriormente conhecido como Swagger). Ela se integra diretamente em aplicações ASP.NET Core, permitindo que desenvolvedores, testadores e consumidores de API entendam e interajam facilmente com seus endpoints.

Por que usar?

• Automação da documentação: Você não precisa mais escrever e manter documentação manualmente. O Swashbuckle analisa seus controladores, modelos e atributos, criando documentação atualizada automaticamente.
• Interface interativa (Swagger UI): A biblioteca fornece uma interface web onde você pode visualizar todos os endpoints, seus parâmetros, modelos de dados e até executar requisições de teste diretamente do navegador.
• Padronização: OpenAPI é um padrão da indústria. A documentação gerada pode ser usada para gerar automaticamente SDKs de cliente em várias linguagens (JavaScript, Python, Java, etc.).
• Facilidade de teste e depuração: Desenvolvedores e engenheiros de QA podem testar APIs rapidamente sem precisar de ferramentas externas como Postman (embora o Postman também possa importar a especificação OpenAPI).

O Swashbuckle é composto por dois componentes principais: Swashbuckle.AspNetCore.Swagger (geração da especificação JSON OpenAPI) e Swashbuckle.AspNetCore.SwaggerUI (exibição da interface interativa).

Instalação

O Swashbuckle é instalado através do gerenciador de pacotes NuGet. Você pode usar o console do gerenciador de pacotes, a .NET CLI ou a interface do Visual Studio.

Via .NET CLI (recomendado)

dotnet add package Swashbuckle.AspNetCore

Via Package Manager Console no Visual Studio

Install-Package Swashbuckle.AspNetCore

Este comando instalará o pacote principal, que inclui todos os componentes necessários: Swagger, SwaggerUI e Swashbuckle.Core.

Início rápido com exemplo de código

Vamos configurar o Swashbuckle minimamente para uma Web API ASP.NET Core.

1. Crie um novo projeto Web API

dotnet new webapi -n MySwaggerApi
cd MySwaggerApi

2. Adicione o Swashbuckle

dotnet add package Swashbuckle.AspNetCore

3. Configure o Program.cs

Abra o arquivo Program.cs e adicione as seguintes linhas:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Adiciona serviços do Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Minha API Incrível",
        Version = "v1",
        Description = "Uma API de exemplo para demonstrar o Swashbuckle"
    });
});

var app = builder.Build();

// Habilita o middleware do Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// Exemplo de endpoint simples
var summaries = new[]
{
    "Congelante", "Fresco", "Frio", "Agradável", "Suave", "Quente", "Morno", "Muito Quente", "Escaldante", "Torrando"
};

app.MapGet("/previsaotempo", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new PrevisaoTempo
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetPrevisaoTempo");

app.Run();

record PrevisaoTempo(DateOnly Data, int TemperaturaC, string? Resumo)
{
    public int TemperaturaF => 32 + (int)(TemperaturaC / 0.5556);
}

4. Execute a aplicação

dotnet run