Generación de modelos Typescript fuertemente tipados desde Umbraco con Swagger y Open API
La API de entrega de contenido de Umbraco simplifica la gestión de un CMS sin cabeza, permitiendo que el contenido gestionado en Umbraco salga en un formato consumible por clientes sin cabeza. Estos clientes pueden ir desde sitios web .NET Core a dispositivos IoT, pero la mayoría serán clientes basados en JavaScript como Next.js, Nuxt.js, Angular Universal, y sus homólogos del lado del cliente, entre otros.
Desde mi punto de vista, las ventajas de TypeScript sobre JavaScript plano son sustanciales. TypeScript ofrece seguridad tipográfica, mejores herramientas y una mejor capacidad de mantenimiento, lo que lo convierte en la opción preferida para proyectos web front-end significativos. Por lo tanto, confiar únicamente en JavaScript plano no es aconsejable. Sin embargo, la Content Delivery API de Umbraco no entrega Swagger tipado por defecto. Entonces, ¿cómo solucionamos esto?
El estado actual y una llamada a la acción
En primer lugar, es importante señalar que la solución descrita a continuación aún no está disponible para Umbraco 14. En segundo lugar, un mensaje directo a la sede de Umbraco: el valor de esta solución es lo suficientemente importante como para que se integre en el código base de Umbraco en lugar de seguir siendo un complemento de la comunidad.
El mérito es nuestro
La base de esta solución la proporciona el paquete Umbraco Delivery API Extensions, creado por los coautores de ByteCrumb Laura Neto y Vitor Rodrigues. Al instalar este sencillo paquete NuGet, la API de entrega entrega Swagger tipado, incluyendo información de tipo de campo, como se detalla en el sitio web del paquete.
Generación de tipos TypeScript a partir de Swagger tipado
El siguiente paso consiste en generar tipos TypeScript a partir del Swagger tipado. Para ello, hemos seguido el artículo de Rick Butterfield: TypeScript OpenAPI Umbraco Content Delivery. Para la mayoría de los proyectos front-end, esto implica dos pasos:
- Instalar una librería de generación de código TypeScript, como openapi-typescript-codegen.
- Crear un script para generar los tipos TypeScript e integrarlos en tu proyecto.
Dado que es probable que los tipos de documento de Umbraco evolucionen durante el desarrollo, este script debería ser fácilmente invocable e incluirse en los scripts de compilación package.json.
Notas de implementación
- La librería openapi-typescript-codegen genera tanto un cliente OpenAPI como los tipos TypeScript. Dado que utilizamos Next.js para este sitio web, optamos por utilizar Next.js' Fetch para realizar todas las llamadas a la API, aprovechando las funciones de caché y revalidación de Next.js.
- Typed Swagger puede ser beneficioso más allá de los proyectos web basados en TypeScript. Por ejemplo, un cliente headless .NET Core podría utilizar el mismo Swagger tipado para generar clases para su consumo en ese sitio web.
Conclusión
Los beneficios de TypeScript son lo suficientemente sustanciales como para considerar comenzar un nuevo proyecto en Umbraco 13 para aprovechar el paquete Umbraco Delivery API Extensions, con un plan para migrar a Umbraco 14 una vez que el paquete esté disponible. ¡Feliz programación!
