Formation Apprendre TypeScript : Typer une fonction basée sur OpenApi

Dans ce tutoriel je vous propose de découvrir la librairie @grafikart/o2ts qui vous permettra de convertir un fichier de définition OpenAPI 3+ en type TypeScript.

L'objectif

L'objectif est de créer une fonction qui va appeler l'API et nous renvoyer les résultats. La signature ressemblera à ça fetchAPI(endpoint, options) et on souhaite que Typescript vérifie les paramètres :

• endpoint devra correspondre à un point d'entrée de notre API.
• options.method contiendra la méthode HTTP à utiliser, et correspondra au endpoint donné.
• options.query devra être un objet qui correspond à ce qu'accepte l'API au niveau des query parameters.
• options.urlParams permettra d'ajouter des paramètres dans l'URL (si le endpoint est /post/{id} par exemple on s'attendra à ce que id soit requis)
• options.body devra être un objet si la requête attend un corps en application/json.
• La réponse devra automatiquement être typée en fonctions des paramètres reçus.

La solution

Dans une première itération j'avais essayé d'utiliser la librairie openapi-typescript mais elle traduit le fichier OpenAPI de manière trop littérale et l'extraction des informations nécessite des types utilitaires complexes qui rende les types difficils à déboguer.

C'est pour cela que j'ai décidé de créer mon propre outil, @grafikart/o2ts, qui va directement extraire les informations importantes du fichier OpenAPI avec des types utilisables. La librairie va générer quelques types utilitaires que vous pourrez utiliser dans vos fonctions.

• APIPaths, représentera tous les endpoints possible
• APIMethods<Path>, représentera toutes les méthodes possible pour un endpoint donné
• APIRequests<Path>, renverra toutes les requêtes possible pour le endpoint
• APIRequest<Path, Method>, renverra le type de la requête à faire pour ce endpoint
• APIResult<Path, Method>, renverra la type de la réponse du serveur
• APISchema<Schema>, permet d'accéder aux schémas définis dans le fichier OpenAPI