Documentación de APIs con OpenAPI y Swagger en .NET

La documentación clara y estandarizada potencia la adopción de una API. Con OpenAPI, Swagger y la librería nativa de .NET 10, puedes describir cada endpoint, parámetros, modelos y tipos de respuesta HTTP para que cualquier cliente entienda cómo consumirla, sin importar el lenguaje o framework usado.

¿Por qué documentar APIs REST con OpenAPI y Swagger?

Documentar permite saber qué hace cada endpoint, qué recibe y qué devuelve, incluidos los posibles códigos HTTP. El estándar OpenAPI es ampliamente comprendido y soportado por múltiples librerías, lo que facilita la colaboración entre equipos. En .NET 10 puedes usar tanto Swagger como la librería nativa de OpenAPI. Incluso, hay alternativas visuales como Scalar para explorar la documentación generada.

• OpenAPI es el estándar más usado para describir APIs REST.
• Swagger genera el archivo OpenAPI en JSON y provee una UI interactiva.
• Plantilla nativa de .NET 10 incluye AddOpenAPI y MapOpenAPI.
• Scalar ofrece otra interfaz gráfica para la misma especificación.

¿Cómo instalar y configurar Swagger y OpenAPI paso a paso?

La idea es generar el documento OpenAPI y una interfaz visual para explorarlo y probarlo. Puedes instalar paquetes por NuGet o con la CLI de .NET, verificando que correspondan a .NET 10.

¿Qué paquetes NuGet instalar para Swagger?

• Buscar en NuGet por “Swagger”.
• Instalar: el paquete base, SwaggerGen y Swagger UI.
• Aceptar la licencia e integrar al proyecto.
• Alternativa: agregar la referencia en el archivo del proyecto.

¿Cómo habilitar el servicio y middleware de Swagger?

• Registrar el generador de Swagger en los servicios.
• Activar el middleware para el documento JSON y la UI.

// En Program.cs
builder.Services.AddSwaggerGen();

app.UseSwagger();          // genera el archivo OpenAPI en JSON
app.UseSwaggerUI();        // expone la interfaz gráfica

• Si la plantilla ya trae OpenAPI nativo, verás llamadas como AddOpenAPI y MapOpenAPI.

// OpenAPI nativo de .NET 10
builder.Services.AddOpenApi();
app.MapOpenApi();

¿Cómo visualizar la documentación y probar endpoints?

• Navegar a la ruta /swagger para abrir Swagger UI.
• Usar “try it out” para ejecutar llamadas y ver la respuesta.
• Observar campos obligatorios y ejemplos de parámetros.
• Entender que el archivo OpenAPI en JSON es “la documentación real”; la UI solo consume ese JSON y lo presenta de forma interactiva.

¿Cómo usar la librería nativa y Scalar para una alternativa visual?

Desde .NET 10, Swagger ya no viene por defecto en la plantilla: se aligeró para que cada equipo elija su librería. La librería nativa de OpenAPI genera el documento y puedes visualizarlo con Swagger UI o con Scalar. Así obtienes dos opciones de interfaz para el mismo estándar.

¿Cómo instalar y mapear Scalar?

• Detener la ejecución.
• Instalar el paquete “Scalar” desde NuGet.
• Mapear su UI después de MapOpenAPI.

// En Program.cs, tras MapOpenApi
app.MapOpenApi();
app.MapScalarApiReference(); // por defecto toma el JSON generado por OpenAPI nativo

• Si necesitas un nombre o ubicación personalizada del JSON, configura las opciones en los paréntesis.
• Abrir /scalar para explorar la interfaz: muestra estructura de respuestas y permite “test request”, incluyendo cookies, headers y query.

¿Cómo enriquecer la documentación con comentarios XML y respuestas HTTP?

Puedes añadir descripciones en el código con comentarios de triple slash (///). Luego, generar el archivo de documentación para incluir esos comentarios en el documento OpenAPI consumido por Swagger o Scalar.

¿Cómo escribir comentarios triple slash en controladores?

• Escribir “///” encima de un endpoint para crear el bloque.
• Completar summary, returns y describir parámetros.

/// <summary>
/// Return all weather forecasts.
/// </summary>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
    // ...
}

/// <summary>
/// Return the weather by position.
/// </summary>
/// <param name="id">Position in the collection.</param>
/// <returns>The element by position.</returns>
[HttpGet("{id}")]
public ActionResult<WeatherForecast> GetById(int id)
{
    // ...
}

¿Cómo generar el archivo de documentación e integrarlo?

• En el archivo del proyecto, agregar un PropertyGroup para generar la documentación incluyendo comentarios.

<!-- En .csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <!-- configuración para generar el archivo de documentación XML -->
  </PropertyGroup>
</Project>

• En Program, ajustar la configuración de Swagger para que use la documentación transformada del assembly y tome los comentarios del código.
• Con esto, verás en Swagger UI descripciones como “Return all weather forecasts” y detalles de parámetros (por ejemplo, que “id” representa una “position”).
• Puedes especificar, con una etiqueta de “produce”, los posibles códigos HTTP (200, 500, bad request) para dejar claro qué devuelve cada endpoint.

— ¿Te animas al reto? Documenta al menos dos endpoints con comentarios y explora cómo agregar un título y una descripción global a la documentación de Swagger. Cuéntame en los comentarios qué tal te fue y qué opción de UI prefieres: Swagger o Scalar.