4 opciones para sustituir Swagger en las API de .NET 9

Configuración de un proyecto de API estándar

Tim comienza creando un proyecto de API mínimo en Visual Studio, eligiendo la plantilla estándar de API web ASP.NET Core.

Hace hincapié en marcar la casilla para añadir compatibilidad con OpenAPI, lo que garantiza que su proyecto incluye la generación de documentos OpenAPI necesaria a través de un punto final de archivo JSON.

Una vez que el proyecto está en marcha, Tim navega a la URL predeterminada del documento OpenAPI (por ejemplo, /swagger/v1/swagger.json) para ver las especificaciones OpenAPI sin procesar. Este archivo contiene metadatos estructurados sobre sus puntos finales de API, incluidos los verbos admitidos como GET, POST y DELETE.

Aunque funcional, Tim señala que la visualización del documento OpenAPI en bruto no es fácil de usar. Para ofrecer una mejor interfaz de documentación basada en web, pasa a mostrar cuatro herramientas externas que mejoran la experiencia del desarrollador y del consumidor.

Opción 1: Swagger UI - La experiencia familiar

Swagger UI sigue siendo una herramienta muy popular, aunque ya no se incluya por defecto. Tim demuestra cómo recuperarlo utilizando el paquete NuGet dotnet necesario: Swashbuckle.AspNetCore.SwaggerUI.

Después de configurar la interfaz de usuario Swagger en un nuevo proyecto, a las 9:43, configura el middleware utilizando sintaxis simplificada y establece la URL de lanzamiento en /swagger. Esta interfaz de usuario proporciona una interfaz de documentación de API fácil de usar en la que los desarrolladores pueden ver los puntos finales, comprender los parámetros de solicitud y probarlos en el navegador.

Aunque Swagger UI es ahora una herramienta externa, sigue siendo compatible con las especificaciones OpenAPI y sigue siendo una de las mejores opciones para las necesidades básicas de documentación durante el desarrollo.

Opción 2: ReDoc - Documentación de API limpia y de solo lectura

La segunda herramienta de Tim es ReDoc, que transforma tu documento OpenAPI en un sitio HTML pulido y de sólo lectura. Después de añadir el paquete OpenAPI Swashbuckle.AspNetCore.ReDoc, asigna la documentación a /api/docs.

A diferencia de Swagger UI, ReDoc no permite realizar pruebas de punto final. Sin embargo, brilla como una interfaz de documentación basada en web adecuada para usuarios externos y clientes. Si su trabajo se centra exclusivamente en la definición de API REST y la presentación de documentación estructurada, ReDoc es la solución perfecta.

Cabe destacar que ReDoc genera automáticamente contenidos basados en las especificaciones OpenAPI proporcionadas, que abarcan las respuestas, los parámetros y los tipos de datos esperados. Esto se ajusta bien a los proyectos que dan prioridad a un soporte integrado optimizado para la documentación frente a la interactividad.

Opción 3: NSwag - Documentación + Generación de código

A continuación, Tim se sumerge en NSwag, una herramienta flexible y rica en funciones que no se limita a documentar API, sino que también puede generar código para clientes en varios lenguajes como C#, TypeScript, etc. Tras instalar el paquete NuGet NSwag.AspNetCore, configura la interfaz tipo Swagger, asignándola al mismo punto final JSON.

Tim explica que NSwag es compatible tanto con las especificaciones Swagger como con los estándares OpenAPI, lo que permite a los desarrolladores elegir el formato que prefieran. Aunque la interfaz de usuario pueda parecer similar a Swagger, son las bibliotecas de herramientas externas y las funciones avanzadas (como la creación automática de clientes) las que hacen brillar a NSwag.

Señala que la capacidad de NSwag para generar código es útil para reducir el esfuerzo manual a la hora de integrarse con API, especialmente en proyectos en los que intervienen múltiples servicios o herramientas externas. Se trata de una potente solución para equipos que construyen una sólida comunicación cliente-servidor.

Opción 4: Scaler - El favorito de Tim para pruebas de API

Tim presenta Scaler UI como su favorito personal entre todas las opciones, describiéndolo como una mezcla de Postman y documentación en el navegador. Después de añadir el paquete Scaler.AspNetCore, sólo se necesita una línea de código (app.MapScalerApiReference()) para habilitar la interfaz.

Scaler admite una interactividad total, incluida la ejecución de solicitudes con parámetros de consulta, cabeceras y cookies. Lo que lo distingue es la información en tiempo real: devuelve el tiempo de respuesta, las cabeceras y las cargas útiles de los resultados al instante.

Una característica destacada de Scaler es su capacidad para generar comandos curl y fragmentos de código cliente para distintos lenguajes (PHP, Node, Python, C# mediante HttpClient y RestSharp). A Tim le resulta especialmente útil para copiar y pegar rápidamente llamadas a API durante el desarrollo.

Scaler también permite alternar entre los modos claro y oscuro, lo que la convierte en una plataforma de documentación de API fácil de usar con margen de mejora. Como plataforma API de código abierto, Scaler sigue evolucionando con un mantenimiento activo y un gran interés por parte de la comunidad.

Pensamientos finales: Las opciones aportan flexibilidad

En los últimos minutos del vídeo, Tim subraya que eliminar Swagger UI de las plantillas web .NET puede parecer un paso atrás, pero en realidad es una oportunidad para adoptar soluciones modernas y más adaptadas. Este cambio se ajusta a los rápidos ciclos de publicación de Microsoft, en los que las funciones son cada vez más modulares y específicas.

El soporte OpenAPI actúa ahora más como un soporte ciudadano de primera clase que como una implementación nativa rígida. Eres libre de mezclar y combinar herramientas en función de las necesidades de tu proyecto, ya sean pruebas interactivas con Scaler, generación de código cliente con NSwag o resultados limpios con ReDoc.

Tim anima a los desarrolladores a explorar estas herramientas, a ver cuál se adapta mejor a su flujo de trabajo e incluso a utilizar varias interfaces de usuario para distintos entornos (por ejemplo, una para el desarrollo y otra para la documentación pública). El hecho de que todas estas opciones sean compatibles con las especificaciones OpenAPI y Swagger significa que no estás atado a un único proveedor o flujo de trabajo.

Conclusión

Gracias a la eliminación de Swagger UI por defecto en .NET 9, los desarrolladores tienen ahora la libertad de elegir la mejor herramienta para sus necesidades de documentación de OpenAPI. Tanto si se trata de documentar API HTTP como de servir a herramientas externas o de apoyar el desarrollo interno, existe una solución que se ajusta a sus objetivos.

Con herramientas como Swagger UI, ReDoc, NSwag y Scaler, documentar y probar APIs nunca ha sido tan personalizable ni tan fácil para los desarrolladores. Como nos muestra Tim Corey en su vídeo, todo lo que se necesita son unos cuantos paquetes, un par de líneas de código y el deseo de explorar las herramientas que mejor sirvan a tu aplicación y a tu equipo.