Adicionando Swagger UI a .NET Aspire no Linux

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.