Una buena documentación es tan importante como una API bien diseñada. Sin documentación clara, los desarrolladores pueden tener dificultades para comprender cómo consumir los servicios, qué parámetros enviar o qué respuestas esperar. En el ecosistema de .NET, la combinación de OpenAPI y Swagger se ha convertido en el estándar para documentar APIs REST de forma automática, interactiva y profesional.
¿Qué son OpenAPI y Swagger?
Aunque muchas personas los utilizan como sinónimos, no son exactamente lo mismo:
- OpenAPI es una especificación que define cómo describir una API REST de manera estandarizada.
- Swagger es un conjunto de herramientas que implementan la especificación OpenAPI, permitiendo generar documentación visual, probar endpoints y generar clientes automáticamente.
En ASP.NET Core, la documentación puede generarse prácticamente de forma automática gracias a paquetes como Swashbuckle.AspNetCore.
Configuración básica en ASP.NET Core
El primer paso consiste en instalar el paquete correspondiente:
dotnet add package Swashbuckle.AspNetCore
Después, registra Swagger en Program.cs:
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();
app.MapControllers();
app.Run();
Al ejecutar la aplicación podrás acceder a una interfaz web donde todos los endpoints aparecerán organizados automáticamente.
Agregar información de la API
Una documentación profesional debe incluir información básica del proyecto:
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new()
{
Title = "API de Inventario",
Version = "v1",
Description = "API para la gestión de productos y categorías."
});
});
Esto facilita que otros desarrolladores identifiquen rápidamente el propósito de la API.
Documentar modelos y endpoints
Utiliza nombres descriptivos para clases, propiedades y métodos.
Ejemplo:
public class CrearProductoRequest
{
public string Nombre { get; set; }
public decimal Precio { get; set; }
public int CategoriaId { get; set; }
}
Los nombres claros permiten que Swagger genere documentación comprensible sin necesidad de configuraciones adicionales.
Aprovechar los comentarios XML
Una de las mejores prácticas consiste en habilitar la generación de comentarios XML.
Ejemplo:
/// <summary>
/// Obtiene un producto por su identificador.
/// </summary>
/// <param name="id">Identificador del producto.</param>
/// <returns>Información completa del producto.</returns>
Luego se configura Swagger para leer dicho archivo XML:
options.IncludeXmlComments(xmlPath);
De esta manera cada endpoint mostrará descripciones, parámetros y respuestas mucho más detalladas.
Documentar códigos de respuesta
Es recomendable indicar los posibles códigos HTTP utilizando atributos:
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
Así los consumidores conocen todos los escenarios posibles antes de integrar la API.
Configurar autenticación JWT
Si la API utiliza JWT, Swagger también puede autenticarse.
Se configura un esquema de seguridad:
options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer",
BearerFormat = "JWT"
});
Después aparecerá el botón Authorize, permitiendo probar endpoints protegidos sin herramientas externas.
Organizar la documentación
Cuando una API crece es recomendable agrupar los controladores por módulos utilizando etiquetas (Tags) o versiones.
Ejemplo:
- Productos
- Usuarios
- Ventas
- Facturación
Esto mejora considerablemente la navegación dentro de Swagger UI.
Buenas prácticas
Para obtener una documentación realmente útil:
- Utiliza nombres claros y consistentes.
- Describe todos los parámetros importantes.
- Documenta ejemplos de entrada y salida.
- Explica los posibles errores.
- Mantén la documentación sincronizada con el código.
- Versiona la API cuando existan cambios incompatibles.
- Protege Swagger en producción si contiene información sensible.
Swagger y OpenAPI permiten convertir la documentación de una API en un proceso prácticamente automático. Sin embargo, una buena documentación no depende únicamente de generar la interfaz visual, sino de proporcionar descripciones claras, modelos bien definidos, respuestas documentadas y ejemplos útiles. Implementando estas buenas prácticas en ASP.NET Core, cualquier equipo podrá desarrollar APIs más fáciles de consumir, mantener y escalar, mejorando la experiencia tanto de desarrolladores internos como de clientes externos.
