Swagger/OpenAPI para C# (.NET): Geração e documentação de API

Geração Swagger/OpenAPI para C# (.NET)

Swagger (agora oficialmente conhecido como OpenAPI) é uma ferramenta poderosa para projetar, criar, documentar e usar APIs RESTful. No ecossistema .NET, a geração de especificações OpenAPI e documentação interativa tornou-se parte essencial do desenvolvimento de serviços web modernos. Neste artigo, veremos detalhadamente como configurar a geração automática de Swagger/OpenAPI em aplicações C# (.NET), usando a biblioteca Swashbuckle.AspNetCore.

Swagger não só permite criar automaticamente documentação legível, mas também fornece uma interface interativa (Swagger UI) para testar endpoints diretamente do navegador. Isso acelera significativamente o desenvolvimento e a integração entre equipes.

Instalação e configuração do Swashbuckle no .NET

Para começar, precisamos instalar o pacote Swashbuckle.AspNetCore. Este é o pacote principal que inclui o gerador Swagger, Swagger UI e integração com ASP.NET Core.

Instalação via NuGet Package Manager Console:

Install-Package Swashbuckle.AspNetCore

Ou via .NET CLI:

dotnet add package Swashbuckle.AspNetCore

Após instalar o pacote, é necessário configurar os serviços no arquivo Program.cs (ou Startup.cs para versões mais antigas). Vejamos uma configuração mínima para .NET 8 e superior:

var builder = WebApplication.CreateBuilder(args);

// Adiciona serviços Swaggerbuilder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo    {        Title = "My API",        Version = "v1",        Description = "Exemplo de API com documentação Swagger"    });});

builder.Services.AddControllers();

var app = builder.Build();

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

app.UseHttpsRedirection();app.MapControllers();

app.Run();

Principais recursos do Swashbuckle

• Geração automática de especificação OpenAPI — a biblioteca analisa seus controladores, modelos de dados e atributos, criando um arquivo de especificação JSON/YAML.
• Swagger UI interativo — interface web onde é possível visualizar endpoints, enviar requisições e ver respostas.
• Suporte a comentários XML — se você adicionar documentação XML aos seus controladores e modelos, o Swagger a exibirá na interface.
• Agrupamento por versões — é possível criar várias versões de documentação para diferentes versões da API.
• Personalização — possibilidade de customizar a aparência, adicionar cabeçalhos, esquemas de autenticação (JWT, Basic Auth) e muito mais.

Adicionando comentários XML para documentação

Para que sua documentação seja informativa, use comentários XML. Primeiro, habilite a geração do arquivo XML no projeto. Abra o arquivo .csproj e adicione:

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <NoWarn>$(NoWarn);1591</NoWarn></PropertyGroup>

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

builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });        // Especifica o caminho para o arquivo XML de documentação    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Agora os comentários do seu código serão exibidos no Swagger UI. Exemplo de controlador com comentários:

/// <summary>