Swagger UI ha sido una herramienta popular y útil para generar documentación interactiva para WebAPI en proyectos basados en .NET. Sin embargo, a partir de .NET 9, Microsoft ha decidido eliminar Swagger UI de las plantillas predeterminadas, buscando una solución más optimizada y con soporte directo: la integración de OpenAPI.

¿Qué es Swagger UI y OpenAPI?

Swagger UI es una herramienta de código abierto que crea automáticamente una interfaz web para interactuar con WebAPIs y es compatible con OpenAPI, una especificación estándar para definir API REST. Aunque fue ampliamente utilizada en versiones anteriores de .NET Core, Microsoft ha optado por integrar una solución propia para mejorar la seguridad y el control del proceso.

¿Por qué Swagger fue eliminado en .NET 9?

La eliminación de Swagger UI se debió principalmente a la falta de mantenimiento activo del proyecto y a los problemas que surgieron con su adaptación a nuevas versiones de .NET. Microsoft ha creado un nuevo paquete, Microsoft.AspNetCore.OpenApi, que proporciona una generación de documentación OpenAPI nativa y sin depender de herramientas de terceros, lo que permite una integración más sencilla y ágil en las aplicaciones .NET.

Ventajas del nuevo paquete OpenAPI de Microsoft

• Soporte Nativo: Al reducir la dependencia de herramientas externas, OpenAPI en .NET 9 ofrece una solución optimizada que se adapta perfectamente a la plataforma.
• Fácil Configuración: No se requieren configuraciones adicionales ni integraciones con herramientas externas, simplificando la implementación de la documentación OpenAPI.
• Compatibilidad con APIs Mínimas: Esta solución se adapta bien a las APIs mínimas introducidas en .NET 6, generando automáticamente metadatos de rutas, parámetros de solicitud y respuestas.
• Compatibilidad con Herramientas Existentes: Aunque Microsoft ofrece una solución nativa, aún es posible utilizar la documentación generada con Swagger o NSwag si es necesario.

Cómo utilizar OpenAPI en .NET 9

Al crear un nuevo proyecto en .NET 9, OpenAPI se agrega automáticamente. Si estás actualizando un proyecto existente, solo debes agregar el paquete Microsoft.AspNetCore.OpenApi y configurarlo con unas pocas líneas de código en el archivo Program.cs.

Alternativas de Herramientas Externas

Además de la solución integrada de Microsoft, existen otras herramientas como Scalar, una plataforma de código abierto para generar documentación API interactiva y fácil de usar, que también es compatible con OpenAPI y Swagger.

Conclusión
La evolución de las herramientas para la documentación de APIs en .NET refleja un esfuerzo continuo por parte de Microsoft para simplificar y optimizar el desarrollo en su plataforma. Con la eliminación de Swagger UI y la integración directa de OpenAPI en .NET 9, los desarrolladores ahora tienen a su disposición una solución más coherente y fácil de implementar, que no depende de bibliotecas de terceros. Este cambio también refleja un enfoque hacia una mayor seguridad y un ciclo de desarrollo más ágil, eliminando la sobrecarga de mantener integraciones externas.

Además, el hecho de que esta solución mantenga compatibilidad con herramientas ya existentes como Swagger o NSwag es una gran ventaja, permitiendo a los desarrolladores elegir la opción que mejor se adapte a sus necesidades. En definitiva, la integración de OpenAPI en .NET 9 parece ser un paso hacia la simplificación de la documentación de APIs, ofreciendo a los desarrolladores una alternativa robusta, fácil de usar y bien soportada.

Para mayor información, visita el artículo original en Medium.