Geração de modelos Typescript fortemente tipados a partir do Umbraco com Swagger e API aberta

A Content Delivery API do Umbraco simplifica a gestão de um CMS sem cabeça, permitindo que o conteúdo gerido no Umbraco seja produzido num formato consumível por clientes sem cabeça. Esses clientes podem variar de sites .NET Core a dispositivos IoT, mas a maioria será de clientes baseados em JavaScript, como Next.js, Nuxt.js, Angular Universal e suas contrapartes do lado do cliente, entre outros.

Do meu ponto de vista, as vantagens do TypeScript sobre o JavaScript simples são substanciais. O TypeScript oferece segurança de tipo, melhores ferramentas e melhor capacidade de manutenção, tornando-o a escolha preferida para projetos web front-end significativos. Por isso, não é aconselhável confiar apenas no JavaScript simples. No entanto, a API de entrega de conteúdo do Umbraco não fornece Swagger digitado por padrão. Então, como é que resolvemos isto?

O estado atual e um apelo à ação

Primeiro, é importante notar que a solução descrita abaixo ainda não está disponível para o Umbraco 14. Em segundo lugar, uma mensagem direta para a sede do Umbraco: o valor desta solução é suficientemente significativo para que seja integrada na base de código do Umbraco em vez de continuar a ser um add-on da comunidade.

Crédito onde é devido

A base para esta solução é fornecida pelo pacote Umbraco Delivery API Extensions, criado pelos co-autores do ByteCrumb, Laura Neto e Vitor Rodrigues. Ao instalar este simples pacote NuGet, a API de entrega fornece Swagger digitado, incluindo informações de tipo de campo, conforme detalhado no site do pacote.

Gerando tipos TypeScript a partir do Swagger tipado

O próximo passo envolve a geração de tipos TypeScript a partir do Swagger tipado. Para isso, seguimos o artigo de Rick Butterfield: TypeScript OpenAPI Umbraco Content Delivery. Para a maioria dos projetos de front-end, isso envolve duas etapas:

1. Instalar uma biblioteca de geração de código TypeScript, como a openapi-typescript-codegen.
2. Criar um script para gerar os tipos TypeScript e integrá-los no seu projeto.

Dado que os tipos de documentos do Umbraco são susceptíveis de evoluir durante o desenvolvimento, este script deve ser facilmente chamável e incluído nos scripts de compilação package.json.

Notas de implementação

• A biblioteca openapi-typescript-codegen gera um cliente OpenAPI e os tipos TypeScript. Como usamos Next.js para este site, optamos por usar o Next.js' Fetch para fazer todas as chamadas de API, aproveitando os recursos de cache e revalidação do Next.js.
• O Swagger tipado pode ser benéfico para além dos projectos web baseados em TypeScript. Por exemplo, um cliente headless .NET Core poderia usar o mesmo Swagger tipado para gerar classes para consumo nesse site.

Conclusão

Os benefícios do TypeScript são suficientemente substanciais para considerar o início de um novo projeto no Umbraco 13 para tirar partido do pacote Umbraco Delivery API Extensions, com um plano para migrar para o Umbraco 14 assim que o pacote estiver disponível. Boa programação!