Modernizando a Documentação da sua API .NET [Parte 1]

#.NET
#.NET C#
#API
#API Rest

Introdução

Pessoal, estou participando do Bootcamp da TIVIT com a DIO (.NET backend com IA) e, ao desenvolver um dos desafios de projeto (um sistema de gestão de estacionamentos), decidi estudar mais detidamente à documentação da Microsoft para documentar de forma mais atualizada minha API.

Foi aí que conheci o Scalar. E nesta série de posts (se eu conseguir chegar até o final) quero te ensinar desde o começo, a como trocar o Swagger UI pelo Scalar, até a publicação de uma página estática na web com a documentação da sua API, e isso gratuitamente.

Em primeiro lugar, no entanto, é preciso que você entenda o motivo da minha troca e por que você também deveria considerar fazer essa migração. Até o .NET 9, os templates padrão de WebAPI incluíam o Swagger UI (via Swashbuckle). Só que isso já não é uma realidade. A equipe do .NET descontinuou a integração "nativa" com o Swagger pelos seguintes motivos:

O Swashbuckle não está sendo mantido: Ele já não oferecia suporte oficial desde o .NET 8;
O suporte nativo ao OpenAPI assumiu o lugar: Agora você pode gerar a especificação da sua API nativamente (mais sobre isso depois).

Acontece que o pacote OpenAPI não oferece nativamente nenhum suporte para visualização e interação com a documentação da API. O Swagger UI e o ReDoc continuam sendo ferramentas muito populares, mas foi nesse contexto de descontinuação do suporte do Swashbuckle que surgiu uma ferramenta open-source chamada Scalar, cuja missão é ser a plataforma mais "moderna" e focada na experiência do desenvolvedor.

Segue um print para que vocês vejam como fica mais ou menos a interface (esta é a API sobre a qual falei no início):

Lindo, não?

Motivos para fazer a troca

Existem muitos fatores que podem determinar que ferramenta devemos escolher, e eu sei que não existe a "opção certa" para cada caso. Na verdade, o desenvolvimento de software tem me ensinado muito sobre o valor do pragmatismo em algumas situações. Aqui, eu quero apenas te dar três motivos que me ajudaram a fazer essa troca, ao estudar a documentação da Microsoft e do próprio Scalar:

1. A Experiência Visual (UI/UX)

A primeira coisa que salta aos olhos é o design. O Scalar parece um produto de 2025/2026.

Ele possui Dark Mode nativo (meus olhos agradecem!).
Navegação por meio de menu lateral organizado (ótimo para APIs grandes).
Barra de busca integrada (Ctrl+K) super rápida.

Eu acredito que para um desenvolvedor que abre seu projeto pela primeira vez, a impressão visual conta muito. Sei que existem casos e casos. Eu já ouvi falar de alguns devs que escrevem código no Emacs sem nem usar highlight! Talvez para esses caras, a beleza não seja tão importante. Mas a maioria de nós vai gostar de uma documentação mais organizada e bonita.

2. O "Killer Feature": Snippets de Código Prontos

No Swagger, você tem o botão "Try it out". É ótimo, mas ele só executa a requisição ali.

No Scalar, ao selecionar um endpoint, ele gera automaticamente o código pronto para consumo em diversas linguagens. Isso, para mim, parece aquelas "premium features", mas no Scalar é totalmente gratuito.

Isso facilita absurdamente a vida de quem vai consumir sua API (inclusive a sua, se estiver criando o Frontend depois!).

3. Integração Nativa a partir do .NET 9

Com o lançamento do .NET 9, a Microsoft introduziu o gerador nativo de OpenAPI (Microsoft.AspNetCore.OpenApi). É verdade que ainda é possível voltar para o Swachbuckle e usar o Swagger, mas o fluxo de trabalho vai ficar mais fácil e rápido ao manter o boilerplate do OpenApi, apenas adicionando o pacote do Scalar:

O serviço OpenApi gera o JSON da especificação (rápido e limpo).
O Middleware do Scalar apenas consome e exibe.

É uma arquitetura mais leve, moderna e alinhada com o futuro do ecossistema .NET.

Conclusão

Em resumo, a partir do .NET 9, a geração de especificações de API ficou muito mais simples. Com o Scalar, você consegue obter uma interface elegante e poderosa, que é fácil de configurar, leve e repleta de recursos. Juntos, esse combo representa uma evolução clara em relação à antiga abordagem do Swagger, e por isso, vale a pena pelo menos testar essa nova plataforma.

Confiram o projeto do estacionamento documentado no Scalar:

Se eu conseguir escrever os próximos posts, tentarei criar um passo a passo simples para a migração. Quanto ao meu projeto e documentação, qualquer feedback é bem-vindo! Tenho aprendido muito nos fóruns e artigos aqui na DIO, e sei que às vezes, um comentário têm grande impacto no meu crescimento. Abraço :-)