Generating Strongly Typed Typescript Models from Umbraco with Swagger and Open API

Umbraco's Content Delivery API simplifies the management of a headless CMS, enabling content managed in Umbraco to be output in a format consumable by headless clients. These clients can range from .NET Core websites to IoT devices, but most will be JavaScript-based clients such as Next.js, Nuxt.js, Angular Universal, and their client-side counterparts, among others.

From my perspective, the advantages of TypeScript over plain JavaScript are substantial. TypeScript offers type safety, better tooling, and improved maintainability, making it the preferred choice for significant front-end web projects. Hence, relying solely on plain JavaScript is not advisable. However, Umbraco's Content Delivery API does not deliver typed Swagger by default. So, how do we address this?

The Current State and a Call to Action

First, it's important to note that the solution outlined below is not yet available for Umbraco 14. Secondly, a direct message to Umbraco Headquarters: the value of this solution is significant enough that it should be integrated into the core Umbraco codebase rather than remaining a community add-on.

Credit Where It's Due

The foundation for this solution is provided by the Umbraco Delivery API Extensions package, created by ByteCrumb co-authors Laura Neto and Vitor Rodrigues. By installing this simple NuGet package, the delivery API delivers typed Swagger, including field type information, as detailed on the package website.

Generating TypeScript Types from Typed Swagger

The next step involves generating TypeScript types from the typed Swagger. For this, we followed Rick Butterfield's article: TypeScript OpenAPI Umbraco Content Delivery. For most front-end projects, this involves two steps:

1. Install a TypeScript code generation library, such as openapi-typescript-codegen.
2. Create a script to generate the TypeScript types and integrate them into your project.

Given that Umbraco document types are likely to evolve during development, this script should be easily callable and included in the package.json build scripts.

Implementation Notes

• The openapi-typescript-codegen library generates both an OpenAPI client and the TypeScript types. Since we used Next.js for this website, we opted to use Next.js' Fetch for making all API calls, leveraging Next.js' caching and revalidation features.
• Typed Swagger can be beneficial beyond TypeScript-based web projects. For instance, a .NET Core headless client could use the same typed Swagger to generate classes for consumption in that website.

Conclusion

TypeScript's benefits are substantial enough to consider beginning a new project on Umbraco 13 to take advantage of the Umbraco Delivery API Extensions package, with a plan to migrate to Umbraco 14 once the package becomes available. Happy coding!