Swashbuckle para C# (.NET): guía completa con ejemplos

¿Qué es Swashbuckle y para qué sirve?

Swashbuckle es una potente biblioteca para la plataforma .NET que genera automáticamente documentación interactiva para tus Web API basada en el estándar OpenAPI (anteriormente conocido como Swagger). Se integra directamente en aplicaciones ASP.NET Core y permite a desarrolladores, testers y consumidores de API entender e interactuar fácilmente con tus endpoints.

¿Por qué usarlo?

• Documentación automatizada: No necesitas escribir ni mantener documentación manualmente. Swashbuckle analiza tus controladores, modelos y atributos, creando documentación actualizada al instante.
• Interfaz interactiva (Swagger UI): La biblioteca proporciona una interfaz web donde puedes ver todos los endpoints, sus parámetros, modelos de datos e incluso ejecutar solicitudes de prueba directamente desde el navegador.
• Estandarización: OpenAPI es un estándar de la industria. La documentación generada puede usarse para crear automáticamente SDKs de cliente en diferentes lenguajes (JavaScript, Python, Java, etc.).
• Pruebas y depuración simplificadas: Desarrolladores e ingenieros de QA pueden probar la API rápidamente sin herramientas externas como Postman (aunque Postman también puede importar la especificación OpenAPI).

Swashbuckle consta de dos componentes principales: Swashbuckle.AspNetCore.Swagger (generación de la especificación JSON OpenAPI) y Swashbuckle.AspNetCore.SwaggerUI (visualización de la interfaz interactiva).

Instalación

Swashbuckle se instala a través del administrador de paquetes NuGet. Puedes usar la consola del administrador de paquetes, la CLI de .NET o la interfaz de Visual Studio.

Mediante .NET CLI (recomendado)

dotnet add package Swashbuckle.AspNetCore

Mediante la Consola del Administrador de Paquetes en Visual Studio

Install-Package Swashbuckle.AspNetCore

Este comando instalará el paquete principal, que incluye todos los componentes necesarios: Swagger, SwaggerUI y Swashbuckle.Core.

Inicio rápido con ejemplo de código

Veamos la configuración mínima de Swashbuckle para una Web API de ASP.NET Core.

1. Crea un nuevo proyecto Web API

dotnet new webapi -n MiSwaggerApi
cd MiSwaggerApi

2. Agrega Swashbuckle

dotnet add package Swashbuckle.AspNetCore

3. Configura Program.cs

Abre el archivo Program.cs y agrega las siguientes líneas:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Agregamos servicios de Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Mi API Increíble",
        Version = "v1",
        Description = "Una API de ejemplo para demostrar Swashbuckle"
    });
});

var app = builder.Build();

// Habilitamos el middleware de Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// Ejemplo de un endpoint simple
var summaries = new[]
{
    "Congelado", "Frío", "Fresco", "Templado", "Suave", "Cálido", "Agradable", "Caluroso", "Muy caliente", "Abrasador"
};

app.MapGet("/pronosticotiempo", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new PronosticoTiempo
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("ObtenerPronosticoTiempo");

app.Run();

record PronosticoTiempo(DateOnly Fecha, int TemperaturaC, string? Resumen)
{
    public int TemperaturaF => 32 + (int)(TemperaturaC / 0.5556);
}

4. Ejecuta la aplicación

dotnet run