Se você criou um projeto Web API recentemente no .NET 10 (ou no .NET 9), provavelmente tomou um susto ao rodar a aplicação: cadê a interface do Swagger?

Historicamente, os templates do ASP.NET Core vinham com o pacote Swashbuckle pré-instalado e configurado. No entanto, a Microsoft decidiu remover a dependência direta dele, focando no suporte nativo à especificação OpenAPI.

Se você, assim como a maioria dos desenvolvedores, ainda prefere a interface visual clássica do Swagger para testar seus endpoints, não se preocupe. Neste artigo, vamos ver como trazê-lo de volta em poucos passos.

---

O Novo Cenário do .NET

Agora, o ecossistema do .NET separa a geração do documento OpenAPI (a estrutura JSON/YAML que descreve sua API) da ferramenta de UI (a interface visual que renderiza esse JSON).

Para termos o Swagger rodando perfeitamente no .NET 10, precisamos configurar essas duas partes.

---

Passo a Passo de Configuração

Passo 1: Instalar os Pacotes Necessários

Primeiro, precisamos instalar o pacote nativo de OpenAPI da Microsoft e o pacote de UI do Swashbuckle. Abra o terminal na raiz do seu projeto e execute:

dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore.SwaggerUI

Passo 2: Configurar o Program.cs

Com os pacotes instalados, precisamos injetar os serviços e mapear os middlewares no arquivo Program.cs. O seu código deve ficar parecido com o exemplo abaixo:

var builder = WebApplication.CreateBuilder(args);

// 1. Adiciona os serviços necessários para gerar o documento OpenAPI
builder.Services.AddOpenApi();

var app = builder.Build();

// 2. Configura o pipeline HTTP para o ambiente de Desenvolvimento
if (app.Environment.IsDevelopment())
{
    // Gera o endpoint do JSON da OpenAPI (ex: /openapi/v1.json)
    app.MapOpenApi();
    
    // Ativa a interface visual do Swagger apontando para o JSON gerado acima
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Minha API .NET 10 v1");
    });
}

app.UseHttpsRedirection();

// Seu endpoint de exemplo
app.MapGet("/weatherforecast", () => "Olá do .NET 10!")
   .WithName("GetWeatherForecast")
   .WithOpenApi(); // Opcional: Garante que o endpoint apareça na documentação

app.Run();

O que mudou no código acima?

Note duas mudanças cruciais em relação ao antigo .NET 6/7/8:

1. builder.Services.AddOpenApi(): Substitui o antigo AddSwaggerGen(). Ele usa o gerador de OpenAPI nativo e otimizado da própria Microsoft.

2. options.SwaggerEndpoint("/openapi/v1.json", ...): Por padrão, o novo gerador nativo expõe o arquivo de especificação na rota /openapi/v1.json (e não mais em /swagger/v1/swagger.json). Precisamos avisar o SwaggerUI onde ler esse arquivo.

Testando a Aplicação

Agora, basta rodar o seu projeto com o comando dotnet run ou dar F5 no seu editor favorito.

Abra o navegador e navegue até a URL padrão do Swagger: https://localhost:XXXX/swagger

Pronto! A interface gráfica clássica do Swagger estará lá, listando todos os seus endpoints de forma documentada e interativa, rodando na velocidade máxima do .NET 10.

Conclusão

Embora a remoção do Swagger dos templates iniciais pareça um passo atrás no quesito conveniência, ela reflete o amadurecimento do .NET em direção a padrões web mais abertos e performáticos. Felizmente, manter o Swagger como nossa ferramenta de UI ainda é extremamente simples e exige pouquíssimas linhas de código.