Modernizando a Documentação da sua API .NET [Parte 2]
No artigo anterior, compartilhei por que decidi abandonar o Swagger no meu projeto de para o bootcamp da TIVIT com a DIO (o T&D Parking) e apostar no Scalar. Hoje, vamos sair da teoria e ir para a prática. Vou te mostrar, linha por linha, como fiz essa migração. A boa notícia, desde já, é que é mais simples do que parece e até limpa bastante o seu código.
Passo 1: A "Faxina" (Removendo o Swashbuckle)
O .NET 9 trouxe uma abordagem nativa para OpenAPI, o que torna a dependência antiga do Swashbuckle desnecessária para a maioria dos casos. Vamos começar removendo o que não precisamos mais.
- Abra seu terminal na pasta do projeto e remova o pacote antigo:
dotnet remove package Swashbuckle.AspNetCore
- Vá no seu Program.cs e apague (ou comente) as linhas referentes ao Swagger antigo:
builder.Services.AddSwaggerGen();
app.UseSwagger();
app.UseSwaggerUI();
Passo 2: Instalando as Novas Ferramentas
Agora, precisamos de dois componentes: o gerador nativo do .NET e a interface do Scalar.
- Garanta que o pacote nativo do ASP.NET Core para OpenAPI esteja instalado. Ele já vem nos templates do .NET 9. Se você tiver removido, insira-o novamente:
dotnet add package Microsoft.AspNetCore.OpenApi
- Instale a integração do Scalar:
dotnet add package Scalar.AspNetCore
Passo 3: Configurando o Program.cs
Aqui é onde a mágica acontece. A configuração é extremamente minimalista. No seu Program.cs, adicione o serviço de OpenAPI e configure o middleware do Scalar. O código ficará assim:
var builder = WebApplication.CreateBuilder(args);
// Passo 1
builder.Services.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
// Passo 2
app.MapOpenApi();
// Passo 3
app.MapScalarApiReference();
}
app.Run();
O que fizemos aqui?
- MapOpenApi(): Cria o arquivo JSON (openapi.json) que descreve sua API.
- MapScalarApiReference(): Pega esse JSON e renderiza aquela interface linda que mostrei no post passado.
Passo 4: Rodando a Aplicação
Salve tudo e rode o projeto (dotnet run ou F5). Diferente do Swagger que geralmente abria em /swagger, o Scalar por padrão estará disponível em:
http://localhost:PORTA/scalar
Ao abrir essa URL, você verá seus endpoints listados com um design limpo, dark mode ativado por padrão e a funcionalidade de gerar snippets de código pronta para uso (gratuita também).
Próximos passos...
Se você notou que sua documentação está bonita, mas sem explicar o que cada campo faz ou o que o endpoint retorna, calma! O Scalar mostra o que o código entrega. Para ter descrições ricas, exemplos de JSON e Enums legíveis, precisamos refinar a nossa documentação.
No próximo artigo, quero te ensinar como usar XML e atributos para transformar essa documentação básica em um guia completo para quem vai consumir sua API.
Funcionou aí? Me conta nos comentários o que achou! 👇
