Geração Swagger/OpenAPI para C# (.NET): Swashbuckle e NSwag

Geração Swagger/OpenAPI para C# (.NET): Swashbuckle e NSwag

Documentar uma API REST é uma parte essencial do desenvolvimento moderno em C# (.NET). A especificação OpenAPI (anteriormente conhecida como Swagger) permite descrever endpoints, modelos de dados, parâmetros e respostas em um formato único e legível por máquina (JSON/YAML). No ecossistema .NET Core / .NET 5+, existem duas ferramentas principais para geração automática de especificações OpenAPI: Swashbuckle.AspNetCore e NSwag. Ambas as ferramentas integram-se ao ASP.NET Core, analisam seu código e criam documentação interativa (Swagger UI).

Swashbuckle.AspNetCore: a escolha clássica

Swashbuckle é o pacote mais popular para geração de Swagger/OpenAPI no .NET. Ele constrói automaticamente a especificação com base em controladores, atributos de rota e anotações de modelos. Suporta OpenAPI 3.0 e Swagger 2.0.

Instalação e configuração básica

dotnet add package Swashbuckle.AspNetCore

No arquivo Program.cs (ou Startup.cs para versões antigas), adicione os serviços e o middleware:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "Minha API",        Version = "v1",        Description = "Exemplo de API para site educacional"    });});

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Minha API v1");    });}

app.MapControllers();app.Run();

Após a execução, acesse /swagger — a UI interativa será aberta, permitindo testar os endpoints diretamente do navegador.

Adicionando comentários XML

Para que as descrições dos comentários XML apareçam na documentação, habilite a geração de XML no .csproj:

<PropertyGroup>  <GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>

Em seguida, especifique o caminho para o arquivo XML no AddSwaggerGen:

builder.Services.AddSwaggerGen(c =>{    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Agora, os comentários do código serão exibidos no Swagger UI.

Exemplo de controlador com anotações

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// Obter lista de todos os produtos    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// Obter produto por ID    /// </summary>    /// <param name="id">Identificador do produto</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "Exemplo" });    }}

NSwag: ferramenta versátil com geração de clientes

NSwag é uma alternativa mais poderosa. Além de gerar documentação, ele pode criar clientes C# para APIs, clientes TypeScript e também gerar código com base em especificações OpenAPI externas.

Instalação e configuração

dotnet add package NSwag.AspNetCore

Configuração no Program.cs:

builder.Services.AddOpenApiDocument(config =>{    config.Title = "Minha API (NSwag)";    config.Version = "v1";    config.Description = "API gerada com NSwag";});

// ...