Documentar una API REST es lo que permite que cualquier persona entienda qué hace cada endpoint, qué recibe, qué devuelve y qué códigos HTTP puede responder. En .NET 10 puedes lograrlo con el estándar OpenAPI, apoyándote en librerías como Swagger o Scalar para generar la interfaz gráfica. Esta guía es para desarrolladores backend que quieren dejar sus APIs listas para que otros las consuman sin fricción.
Por qué OpenAPI es el estándar para documentar APIs
Cuando hablamos de documentación de APIs, OpenAPI es el lenguaje común que usan frameworks y lenguajes de programación para describir endpoints de forma uniforme. Al ser un estándar, cualquier programador entiende la documentación sin importar si la API se construyó en .NET, Node o Python [0:18].
En .NET 10, la plantilla base ya incluye una librería nativa de OpenAPI. Esto se nota en dos líneas que aparecen por defecto en Program.cs: AddOpenApi() para registrar el servicio y MapOpenApi() para exponer el archivo JSON con la descripción de la API [4:50]. Antes Swagger venía por defecto, pero desde la versión 10 se eliminó para aligerar la plantilla y dejar que tú elijas la librería que prefieras.
¿Qué es OpenAPI? Es un estándar que describe en formato JSON o YAML los endpoints de una API, sus parámetros, respuestas y códigos HTTP. Sirve para que humanos y herramientas entiendan cómo consumir la API.
Cómo instalar Swagger en un proyecto .NET 10
Swagger es la librería más conocida para documentar APIs y, además del archivo JSON con el estándar, te entrega una interfaz gráfica para probar cada endpoint en el navegador.
Para instalarlo tienes tres caminos:
- Usar la página de NuGet y copiar el comando para
dotnet cli, asegurándote de elegir la versión compatible con .NET 10.
- Agregar la línea
PackageReference directamente en el archivo .csproj.
- Usar Visual Studio con la opción Manage NuGet Packages sobre el proyecto, buscar Swagger e instalar.
Los paquetes que necesitas son tres: el paquete principal, SwaggerGen (que genera la documentación al compilar) y SwaggerUI (que entrega la interfaz gráfica) [2:40].
Una vez instalados, en Program.cs agregas el servicio con AddSwaggerGen() y, en la sección de middlewares, sumas UseSwagger() para generar el archivo JSON y UseSwaggerUI() para habilitar la interfaz visual [3:20]. Al ejecutar el proyecto y navegar a /swagger, vas a ver tus endpoints listados con un botón Try it out para ejecutarlos directamente desde el navegador.
Cómo usar Scalar como alternativa a Swagger UI
Scalar es otra librería que consume el archivo OpenAPI generado por la plantilla nativa de .NET y presenta una interfaz gráfica distinta, con un diseño más moderno y opciones extendidas para enviar cookies, headers o query params en cada prueba.
La instalación se hace desde NuGet buscando Scalar. Luego, en Program.cs, después de MapOpenApi(), agregas el middleware MapScalarApiReference() [6:30]. No necesitas configurar la ruta del JSON porque Scalar lo busca por defecto en la ubicación que genera la librería nativa.
¿Swagger o Scalar? Ambas consumen el mismo archivo OpenAPI. Swagger es la opción clásica con más comunidad. Scalar ofrece una UI más limpia y permite enviar cookies, headers y queries en las pruebas con menos pasos.
Al ejecutar el proyecto y navegar a /scalar, encuentras los mismos endpoints pero con la opción Test Request, que muestra la estructura de respuesta esperada y permite enriquecer la prueba con datos adicionales [7:40].
Cómo agregar descripciones personalizadas a cada endpoint
La documentación automática está bien, pero queda corta cuando un parámetro se llama id y en realidad representa una posición. Aquí entran los comentarios XML de C#.
Dentro de un controlador, al escribir tres barras (///) sobre un método, Visual Studio genera la estructura con etiquetas como <summary>, <returns> y descripciones de parámetros. Por ejemplo, puedes escribir Return all weather forecast en el summary o Return the element by position en el returns [9:30].
Para que Swagger lea estos comentarios necesitas dos configuraciones:
- En el archivo
.csproj, agregar un nuevo PropertyGroup con la configuración que genera el archivo XML de documentación al compilar.
- En
Program.cs, dentro de AddSwaggerGen(), agregar la transformación que incluye los comentarios del assembly en la documentación generada [11:00].
Con esto, al volver a /swagger, las descripciones aparecen junto a cada endpoint y los parámetros muestran el contexto real, no solo el nombre técnico.
Cómo declarar los códigos HTTP que devuelve un endpoint
Más allá de las descripciones, puedes usar el atributo [Produces] para especificar qué códigos HTTP retorna un método: un 200 cuando todo sale bien, un 500 ante un error interno o un Bad Request si el cliente envía datos inválidos. Esto vuelve la documentación mucho más precisa para quien consume la API [12:20].
Reto de la clase: documenta al menos dos de los endpoints que tienes creados e investiga cómo agregar un título y una descripción general a la documentación de Swagger. Es algo sencillo de lograr y le da contexto inmediato a cualquiera que abra tu API por primera vez. ¿Ya intentaste integrar Swagger o Scalar en tu proyecto? Cuéntame en los comentarios cuál te resultó más cómodo.
