4 opções para substituir o Swagger nas APIs do .NET 9

Configurando um projeto de API padrão

Tim começa criando um projeto de API mínimo no Visual Studio, escolhendo o modelo padrão de API Web do ASP.NET Core .

Ele enfatiza a importância de marcar a caixa para adicionar suporte ao OpenAPI, o que garante que seu projeto inclua a geração necessária de documentos OpenAPI por meio de um endpoint de arquivo JSON.

Assim que o projeto estiver em execução, Tim navega até o URL padrão do documento OpenAPI (por exemplo, /swagger/v1/swagger.json) para visualizar as especificações brutas do OpenAPI. Este arquivo contém metadados estruturados sobre seus endpoints de API, incluindo verbos suportados como GET, POST e DELETE.

Embora funcional, Tim observa que visualizar o documento OpenAPI bruto não é amigável ao usuário. Para proporcionar uma interface de documentação online mais eficiente, ele demonstra quatro ferramentas externas que melhoram a experiência do desenvolvedor e do consumidor.

Opção 1: Swagger UI – A Experiência Familiar

O Swagger UI ainda é uma ferramenta muito popular, mesmo não estando mais incluído por padrão. Tim demonstra como restaurar o recurso usando o pacote NuGet necessário: dotnet: Swashbuckle.AspNetCore.SwaggerUI.

Após configurar a interface do Swagger em um novo projeto, às 9h43, ele configura o middleware usando uma sintaxe simplificada e define a URL de inicialização como /swagger. Esta interface de usuário fornece uma documentação de API amigável, onde os desenvolvedores podem visualizar endpoints, entender parâmetros de requisição e testá-los no navegador.

Embora o Swagger UI seja agora uma ferramenta externa, ele ainda oferece suporte às especificações OpenAPI e continua sendo uma das melhores opções para necessidades básicas de documentação durante o desenvolvimento.

Opção 2: ReDoc – Documentação de API limpa e somente leitura

A segunda ferramenta de Tim é o ReDoc, que transforma seu documento OpenAPI em um site HTML refinado e somente leitura. Depois de adicionar o pacote OpenAPI Swashbuckle.AspNetCore.ReDoc, ele mapeia a documentação para /api/docs.

Diferentemente do Swagger UI, o ReDoc não permite testes de endpoints. No entanto, destaca-se como uma interface de documentação baseada na web, adequada para usuários externos e clientes. Se o seu foco for exclusivamente a definição de APIs REST e a exibição de documentação estruturada, o ReDoc é uma ótima opção.

Vale ressaltar que o ReDoc gera conteúdo automaticamente com base nas especificações OpenAPI fornecidas, abrangendo respostas, parâmetros e tipos de dados esperados. Isso se alinha bem com projetos que priorizam o suporte integrado e otimizado para documentação em detrimento da interatividade.

Opção 3: NSwag – Documentação + Geração de Código

Em seguida, Tim explora o NSwag, uma ferramenta flexível e repleta de recursos que faz mais do que apenas documentar APIs — ela também pode gerar código para clientes em várias linguagens, como C#, TypeScript e muito mais. Após instalar o pacote NuGet NSwag.AspNetCore, ele configura a interface semelhante ao Swagger, mapeando-a para o mesmo endpoint JSON.

Tim explica que o NSwag suporta tanto as especificações Swagger quanto os padrões OpenAPI, permitindo que os desenvolvedores escolham o formato de sua preferência. Embora a interface do usuário possa parecer semelhante à do Swagger, são as bibliotecas de ferramentas externas e os recursos avançados (como a criação automática de clientes) que fazem o NSwag se destacar.

Ele destaca que a capacidade do NSwag de gerar código é útil para reduzir o esforço manual na integração com APIs, especialmente em projetos que envolvem múltiplos serviços ou ferramentas externas. É uma solução poderosa para equipes que desenvolvem uma comunicação robusta entre cliente e servidor.

Opção 4: Scaler – A opção favorita de Tim para testes de API

Tim apresenta o Scaler UI como sua opção favorita dentre todas as disponíveis, descrevendo-o como uma mistura de Postman com documentação no navegador. Após adicionar o pacote Scaler.AspNetCore, apenas uma linha de código (app.MapScalerApiReference()) é necessária para habilitar a interface.

O Scaler oferece suporte à interatividade completa, incluindo a execução de solicitações com parâmetros de consulta, cabeçalhos e cookies. O que o diferencia é o feedback em tempo real — ele retorna o tempo de resposta, os cabeçalhos e os resultados instantaneamente.

Um recurso de destaque do Scaler é sua capacidade de gerar comandos curl e trechos de código do cliente para diferentes linguagens (PHP, Node, Python, C# via HttpClient e RestSharp). Tim considera isso particularmente útil para copiar e colar chamadas de API rapidamente durante o desenvolvimento.

O Scaler também permite alternar entre os modos claro e escuro, tornando-se uma plataforma de documentação de API fácil de usar e com espaço para melhorias futuras. Como uma plataforma de API de código aberto, o Scaler continua a evoluir com manutenção ativa e forte interesse da comunidade.

Considerações finais: Opções trazem flexibilidade.

Nos minutos finais do vídeo, Tim enfatiza que remover o Swagger UI dos modelos web .NET pode parecer um retrocesso, mas na verdade é uma oportunidade para adotar soluções modernas e mais personalizadas. Essa mudança está alinhada aos ciclos de lançamento rápidos da Microsoft, onde os recursos estão se tornando mais modulares e focados.

O suporte ao OpenAPI agora funciona mais como um recurso de primeira classe do que como uma implementação nativa rígida. Você tem a liberdade de combinar as ferramentas de acordo com as necessidades do seu projeto — seja para testes interativos com o Scaler, geração de código do lado do cliente com o NSwag ou saída organizada com o ReDoc.

Tim incentiva os desenvolvedores a explorarem essas ferramentas, verem qual delas se adapta melhor ao seu fluxo de trabalho e, possivelmente, até mesmo usarem várias interfaces de usuário para diferentes ambientes (por exemplo, uma para desenvolvimento e outra para documentação pública). O fato de todas essas opções serem compatíveis com as especificações OpenAPI e Swagger significa que você não está preso a um único fornecedor ou fluxo de trabalho.

Conclusão

Graças à remoção do Swagger UI como padrão no .NET 9, os desenvolvedores agora têm a liberdade de escolher a melhor ferramenta para suas necessidades de documentação OpenAPI. Seja para documentar APIs HTTP, disponibilizar ferramentas externas ou dar suporte ao desenvolvimento interno, existe uma solução que se alinha aos seus objetivos.

Com ferramentas como Swagger UI, ReDoc, NSwag e Scaler, documentar e testar APIs nunca foi tão personalizável ou fácil para desenvolvedores. Como Tim Corey nos mostra em seu vídeo , tudo o que é preciso são alguns pacotes, algumas linhas de código e o desejo de explorar as ferramentas que melhor atendem à sua aplicação e à sua equipe.