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

Generación Swagger/OpenAPI para C# (.NET)

Swagger (ahora oficialmente conocido como OpenAPI) es una herramienta potente para diseñar, crear, documentar y utilizar API RESTful. En el ecosistema .NET, la generación de especificaciones OpenAPI y documentación interactiva se ha convertido en una parte esencial del desarrollo de servicios web modernos. En este artículo, analizaremos en detalle cómo configurar la generación automática de Swagger/OpenAPI en aplicaciones C# (.NET) utilizando la biblioteca Swashbuckle.AspNetCore.

Swagger no solo permite crear automáticamente documentación legible, sino que también proporciona una interfaz interactiva (Swagger UI) para probar los endpoints directamente desde el navegador. Esto acelera significativamente el desarrollo y la integración entre equipos.

Instalación y configuración de Swashbuckle en .NET

Para comenzar, necesitamos instalar el paquete Swashbuckle.AspNetCore. Este es el paquete principal que incluye el generador Swagger, Swagger UI y la integración con ASP.NET Core.

Instalación a través de la Consola del Administrador de Paquetes NuGet:

Install-Package Swashbuckle.AspNetCore

O a través de .NET CLI:

dotnet add package Swashbuckle.AspNetCore

Después de instalar el paquete, es necesario configurar los servicios en el archivo Program.cs (o Startup.cs para versiones anteriores). Veamos una configuración mínima para .NET 8 y superior:

var builder = WebApplication.CreateBuilder(args);

// Agregamos servicios Swaggerbuilder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo    {        Title = "My API",        Version = "v1",        Description = "Ejemplo de API con documentación Swagger"    });});

builder.Services.AddControllers();

var app = builder.Build();

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

app.UseHttpsRedirection();app.MapControllers();

app.Run();

Funcionalidades principales de Swashbuckle

• Generación automática de especificaciones OpenAPI — la biblioteca analiza sus controladores, modelos de datos y atributos, creando un archivo de especificación JSON/YAML.
• Swagger UI interactivo — interfaz web donde puede ver los endpoints, enviar solicitudes y ver las respuestas.
• Soporte para comentarios XML — si agrega documentación XML a sus controladores y modelos, Swagger la mostrará en la interfaz.
• Agrupación por versiones — puede crear múltiples versiones de documentación para diferentes versiones de la API.
• Personalización — posibilidad de personalizar la apariencia, agregar encabezados, esquemas de autenticación (JWT, Basic Auth) y mucho más.

Agregar comentarios XML para la documentación

Para que su documentación sea informativa, use comentarios XML. Primero, habilite la generación del archivo XML en el proyecto. Abra el archivo .csproj y agregue:

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <NoWarn>$(NoWarn);1591</NoWarn></PropertyGroup>

Luego, especifique la ruta al archivo XML en AddSwaggerGen:

builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });        // Especificamos la ruta al archivo XML de documentación    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Ahora los comentarios de su código se mostrarán en Swagger UI. Ejemplo de un controlador con comentarios:

/// <summary>