Generación de Swagger/OpenAPI para C# (.NET): Swashbuckle y NSwag

Generación de Swagger/OpenAPI para C# (.NET): Swashbuckle y NSwag

La documentación de API REST es una parte esencial del desarrollo moderno en C# (.NET). La especificación OpenAPI (anteriormente conocida como Swagger) permite describir endpoints, modelos de datos, parámetros y respuestas en un formato único y legible por máquina (JSON/YAML). En el ecosistema de .NET Core / .NET 5+ existen dos herramientas principales para la generación automática de especificaciones OpenAPI: Swashbuckle.AspNetCore y NSwag. Ambas herramientas se integran en ASP.NET Core, analizan tu código y crean documentación interactiva (Swagger UI).

Swashbuckle.AspNetCore: la elección clásica

Swashbuckle es el paquete más popular para generar Swagger/OpenAPI en .NET. Construye automáticamente la especificación basándose en controladores, atributos de enrutamiento y anotaciones de modelos. Soporta OpenAPI 3.0 y Swagger 2.0.

Instalación y configuración básica

dotnet add package Swashbuckle.AspNetCore

En el archivo Program.cs (o Startup.cs para versiones antiguas), agregue los servicios y el middleware:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "Mi API",        Version = "v1",        Description = "API de ejemplo para sitio educativo"    });});

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Mi API v1");    });}

app.MapControllers();app.Run();

Después de ejecutar, navegue a /swagger — se abrirá una UI interactiva donde puede probar los endpoints directamente desde el navegador.

Agregar comentarios XML

Para que las descripciones de los comentarios XML aparezcan en la documentación, habilite la generación de XML en .csproj:

<PropertyGroup>  <GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>

Luego, especifique la ruta al archivo XML en AddSwaggerGen:

builder.Services.AddSwaggerGen(c =>{    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Ahora los comentarios del código se mostrarán en Swagger UI.

Ejemplo de controlador con anotaciones

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// Obtener la lista de todos los productos    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// Obtener un producto por ID    /// </summary>    /// <param name="id">Identificador del producto</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "Ejemplo" });    }}

NSwag: herramienta versátil con generación de clientes

NSwag es una alternativa más potente. Además de generar documentación, puede crear clientes en C# para la API, clientes en TypeScript, así como generar código basado en especificaciones OpenAPI externas.

Instalación y configuración

dotnet add package NSwag.AspNetCore

Configuración en Program.cs:

builder.Services.AddOpenApiDocument(config =>{    config.Title = "Mi API (NSwag)";    config.Version = "v1";    config.Description = "API generada con NSwag";});

// ...