Agregar Swagger UI a .NET Aspire en Linux

Instalando el paquete NuGet Swashbuckle

[0:38 - 1:35] Tim abre el proyecto Tiny Ticket en VS Code y navega al servicio API's Program.cs. La API ya tiene un endpoint GET /api/tickets del episodio anterior, pero llamarlo requería construir manualmente el URL. Para añadir una interfaz de prueba adecuada, el primer paso es instalar el paquete Swagger UI.

Haga clic derecho en el proyecto API, seleccione "Agregar paquete NuGet" y busque Swashbuckle.AspNetCore.SwaggerUI. Tim instala la última versión (10.1.7 en el momento de la grabación). Después de la instalación, la referencia al paquete aparece en el archivo del proyecto. No se necesitan otras dependencias porque el proyecto ya incluye soporte OpenAPI a través de la configuración de servicio Aspire por defecto.

// 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] Con el paquete instalado, la configuración va en el bloque exclusivo de desarrollo de Program.cs. El proyecto ya tiene app.MapOpenApi() registrado, que genera el archivo de especificación OpenAPI en tiempo de ejecución. Swagger UI simplemente necesita saber dónde reside ese archivo y cómo etiquetar el 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");
    });
}

La llamada SwaggerEndpoint apunta a la especificación OpenAPI que .NET genera automáticamente. El segundo parámetro es un nombre de visualización que aparece en el menú desplegable de Swagger UI. Tim enfatiza que estas tres líneas son toda la configuración Swagger. Podrías añadir más configuración para personalizar la UI, agrupar puntos finales, o añadir encabezados de autenticación, pero para una herramienta de prueba en desarrollo, los valores por defecto son suficientes.

Un detalle que vale la pena mencionar: desde .NET 9, los nuevos proyectos API ya no incluyen Swagger por defecto. Microsoft separó las preocupaciones enviando OpenAPI como el estándar y permitiendo a los desarrolladores elegir su capa de UI preferida. Swagger, Scalar y otras herramientas consumen el mismo archivo de especificación OpenAPI, por lo que no está bloqueado en ningún visor en particular.

Ejecutando y verificando la interfaz Swagger

[3:12 - 6:07] Después de guardar, Tim lanza el proyecto a través del panel Ejecutar y Depurar. Una vez que el Aspire dashboard se carga y el servicio API se muestra como en ejecución, él navega al URL de la API y añade /swagger al camino.

Swagger UI se carga con la etiqueta "Ticket App API v1" y lista los puntos finales disponibles. El endpoint raíz (/) devuelve un simple mensaje de salud, y /api/tickets devuelve los datos del ticket desde la base de datos.

Tim hace clic en "Probar" en el punto final raíz y lo ejecuta. La respuesta regresa con un estado 200 y un mensaje de confirmación. Luego se mueve al endpoint /api/tickets y ejecuta, donde comienza la solución de problemas.

El primer intento falla con un error de conexión: "Ocurrió un error relacionado con la red o específico de la instancia al establecer conexión con el servidor SQL." El contenedor de la base de datos no se había iniciado después de un reinicio de la máquina. Tim abre Portainer, encuentra el contenedor Docker de SQL Server, y lo inicia. Después de que el contenedor termina de inicializarse, regresa a Swagger y ejecuta la solicitud nuevamente. Esta vez, la respuesta devuelve un 200 con los tres tiquetes de prueba almacenados en la base de datos.

Esa secuencia es un recordatorio práctico de que las pruebas de integración contra infraestructura real revelarán problemas que las pruebas unitarias y los datos simulados no pueden. El contenedor de la base de datos no está configurado para iniciar automáticamente al arrancar, lo que significa que la primera llamada a la API después de un reinicio fallará a menos que primero verifiques el estado del contenedor.

Qué sigue: Puntos finales CRUD

[6:07 - 7:20] Tim anticipa los próximos episodios de la serie. La API de Tiny Ticket actualmente solo tiene el endpoint GET /api/tickets, que se asigna al procedimiento almacenado spTickets_GetAll. Los procedimientos almacenados restantes en la base de datos (Obtener por ID, Insertar, Actualizar, Eliminar) necesitan cada uno un endpoint de API correspondiente con el verbo HTTP correcto: GET para recuperación, POST para creación, PUT para actualizaciones, y DELETE para eliminación.

Él señala que cada punto final sigue el mismo patrón y es sencillo de implementar, pero los próximos videos los cubrirán individualmente para que cada parte sea fácil de consultar independientemente. La decisión de dividir la serie en episodios pequeños y enfocados significa que puedes ir directamente al tipo de punto final que necesitas sin tener que avanzar en un video más largo.

Conclusión

[7:20 - 7:24] Agregar Swagger UI a un proyecto .NET Aspire en Linux requiere un paquete NuGet y tres líneas de configuración en Program.cs. El archivo de especificaciones OpenAPI ya es generado por la configuración de servicio Aspire por defecto, por lo que Swagger solo necesita un puntero a ese archivo y un nombre para mostrar. Desde allí, cada punto final en la API es comprobable a través del navegador sin construir un cliente separado.

El problema de conexión a la base de datos que Tim encontró después de reiniciar refuerza un punto práctico: cuando tu pila de desarrollo incluye contenedores, verifica que estén funcionando antes de probar puntos finales API. Swagger te da un ciclo de retroalimentación rápido para esa verificación.

Navegación de la serie: Este artículo es parte de la serie de C# en Linux construyendo la app Tiny Ticket. Anterior: Configurando .NET Aspire en Linux. Siguiente: Añadiendo un Punto Final Get By ID.

Consejo de ejemplo: Si prefieres un visor OpenAPI diferente sobre Swagger, instala un paquete como Scalar o RapiDoc y dirígelo al mismo endpoint /openapi/v1.json. El archivo de especificaciones es independiente de la interfaz de usuario, por lo que puedes cambiar de visor sin cambiar la configuración de tu API.

Mira el video completo en su canal de YouTube y obtén más información sobre la construcción de APIs en la serie de C# en Linux.