Adicionando Swagger UI a .NET Aspire no Linux

Tim Corey

7m 24s

Testar endpoints de API digitando manualmente URLs em um navegador funciona para uma verificação rápida, mas desmorona assim que você tem mais do que algumas rotas com diferentes verbos HTTP e corpos de requisição. Swagger UI oferece a você um painel baseado em navegador interativo onde você pode chamar cada endpoint, inspecionar respostas e experimentar com parâmetros sem escrever um cliente separado ou memorizar flags do curl.

Em seu vídeo "Adding Swagger UI to .NET Aspire on Linux", Tim Corey pega o projeto Tiny Ticket do episódio anterior e adiciona Swagger UI sobre a configuração existente do OpenAPI. O processo leva três linhas de código e um pacote NuGet. Ele então demonstra chamando os endpoints dos tickets através da interface Swagger, incluindo o diagnóstico de um problema de conexão com o banco de dados que não havia iniciado após um reinício da máquina. Se você está construindo APIs na série C# on Linux ou deseja uma referência rápida para conectar o Swagger em um projeto .NET, este artigo cobre cada passo.

Instalando o Pacote NuGet Swashbuckle

[0:38 - 1:35] Tim abre o projeto Tiny Ticket no VS Code e navega para o Program.cs do serviço API. A API já possui um endpoint GET /api/tickets do episódio anterior, mas chamá-lo exigia construir manualmente o URL. Para adicionar uma interface de teste adequada, o primeiro passo é instalar o pacote Swagger UI.

Clique com o botão direito no projeto API, selecione "Adicionar Pacote NuGet" e procure por Swashbuckle.AspNetCore.SwaggerUI. Tim instala a versão mais recente (10.1.7 no momento da gravação). Após a instalação, a referência do pacote aparece no arquivo do projeto. Nenhuma outra dependência é necessária porque o projeto já inclui suporte OpenAPI através da configuração padrão do serviço Aspire.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Configuring Swagger UI in Program.cs

[1:35 - 3:12] Com o pacote instalado, a configuração vai para o bloco somente de desenvolvimento de Program.cs. O projeto já tem registrado app.MapOpenApi(), que gera o arquivo de especificação OpenAPI em tempo de execução. Swagger UI só precisa saber onde esse arquivo está localizado e como rotular o grupo de endpoint.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

A chamada SwaggerEndpoint aponta para a especificação OpenAPI que .NET gera automaticamente. O segundo parâmetro é um nome de exibição que aparece no dropdown do Swagger UI. Tim enfatiza que essas três linhas são toda a configuração do Swagger. Você poderia adicionar mais configuração para personalizar a UI, agrupar endpoints, ou adicionar cabeçalhos de autenticação, mas para uma ferramenta de teste de desenvolvimento, os padrões são suficientes.

Um detalhe que vale a pena notar: desde o .NET 9, novos projetos de API não incluem mais o Swagger por padrão. A Microsoft separou as preocupações ao enviar o OpenAPI como padrão e deixar os desenvolvedores escolherem sua camada de UI preferida. Swagger, Scalar, e outras ferramentas todas consomem o mesmo arquivo spec OpenAPI, então você não está preso a qualquer visualizador em particular.

Executando e Verificando a Interface Swagger

[3:12 - 6:07] Depois de salvar, Tim lança o projeto através do painel Run and Debug. Assim que o painel Aspire carrega e o serviço API aparece como em execução, ele navega até o URL da API e adiciona /swagger ao caminho.

O Swagger UI carrega com o rótulo "Ticket App API v1" e lista os endpoints disponíveis. O endpoint raiz (/) retorna uma mensagem de saúde simples, e /api/tickets retorna os dados do ticket do banco de dados.

Tim clica em "Try it out" no endpoint raiz e o executa. A resposta retorna com um status 200 e uma mensagem de confirmação. Em seguida, ele move-se para o endpoint /api/tickets e executa, onde começa a solução de problemas.

A primeira tentativa falha com um erro de conexão: "Ocorreu um erro de rede ou específico da instância ao estabelecer conexão com o servidor SQL." O contêiner do banco de dados não tinha iniciado após um reinício da máquina. Tim abre o Portainer, encontra o contêiner Docker do SQL Server e o inicia. Depois que o contêiner termina de inicializar, ele retorna ao Swagger e executa a solicitação novamente. Desta vez, a resposta retorna um 200 com os três tickets de teste armazenados no banco de dados.

Essa sequência é um lembrete prático de que testes de integração contra infraestruturas reais irão revelar problemas que testes de unidade e dados simulados não conseguem. O contêiner do banco de dados não está definido para iniciar automaticamente ao inicializar, o que significa que a primeira chamada de API após um reinício falhará a menos que você verifique antes o estado do contêiner.

O que vem a seguir: Endpoints CRUD

[6:07 - 7:20] Tim antecipa os próximos episódios da série. A API Tiny Ticket atualmente tem apenas o endpoint GET /api/tickets, que mapeia para o procedimento armazenado spTickets_GetAll. Os procedimentos armazenados restantes no banco de dados (Obter por ID, Inserir, Atualizar, Excluir) precisam de um endpoint API correspondente com o verbo HTTP correto: GET para recuperação, POST para criação, PUT para atualizações e DELETE para remoção.

Ele observa que cada endpoint segue o mesmo padrão e é direto de implementar, mas os próximos vídeos irão cobri-los individualmente para que cada parte seja fácil de consultar de forma independente. A escolha de dividir a série em episódios pequenos e focados significa que você pode pular diretamente para o tipo de endpoint que precisa sem ter de vasculhar um vídeo mais longo.

Conclusão

[7:20 - 7:24] Adicionar o Swagger UI a um projeto .NET Aspire no Linux exige um pacote NuGet e três linhas de configuração em Program.cs. O arquivo de especificação OpenAPI já é gerado pela configuração padrão do serviço Aspire, então o Swagger só precisa de uma referência para esse arquivo e um nome de exibição. A partir daí, cada endpoint da API é testável através do navegador sem precisar construir um cliente separado.

O problema de conexão com o banco de dados que Tim encontrou após o reinício reforça um ponto prático: quando sua pilha de desenvolvimento inclui contêineres, verifique se eles estão em execução antes de testar endpoints de API. O Swagger lhe oferece um ciclo de feedback rápido para essa verificação.

Navegação da série: Este artigo é parte da série C# on Linux construindo o aplicativo Tiny Ticket. Anterior: Configurando o .NET Aspire no Linux. Próximo: Adicionando um Endpoint Get By ID.

Dica de exemplo: Se você preferir um visualizador OpenAPI diferente do Swagger, instale um pacote como Scalar ou RapiDoc e indique-o no mesmo endpoint /openapi/v1.json. O arquivo de especificação é agnóstico à UI, então você pode trocar de visualizadores sem mudar sua configuração de API.

Assista o vídeo completo vídeo no YouTube Canal dele e obtenha mais insights sobre construção de APIs na série C# on Linux.