SFEIR

SFEIR

26 Nov, 2021

Connecter un front et un back avec Swagger

Rubrique

CodeShake

Dans une quête éternelle d’amélioration, et étant passionné et addict du « strong typing » ou « type safe », Florian Pascouau, développeur Fullstack chez SFEIR a un jour découvert un petit module qui permet de connecter un front et un back avec l’aide de Swagger (renommé OpenApi depuis).

Plus besoin de saisir manuellement (au risque de faire des erreurs d’écriture) les endpoints. Ils sont générés sous forme de méthodes prêtes à être utilisées côté front. En bonus, même les modèles sont générés. Consommer une API n’a jamais été aussi simple. 

Dans cet article, il nous partage sa vision et les enjeux de cet outil : Swagger.

 

Qu’est-ce que Swagger ?

Swagger (ou OpenApi depuis sa version 3) est un outil assez répandu qui permet de documenter une Api Rest de façon standardisée et de décrire de façon précise l’ensemble des endpoints d’un backend, leurs paramètres d’entrée et de sortie.

Mais la façon dont on peut utiliser toutes ces informations générées plus ou moins automatiquement, côté client, reste peu connue.

En effet, dans le cadre d’un projet Angular, j’ai découvert un petit module npm : ng-openapi-gen, qui permet de générer des méthodes prêtes à l’emploi sous forme de services, afin de consommer de façon simplissime notre API.

En bonus, toutes nos entités de base de données / classes / modèles sont générées automatiquement. Fini la duplication de code, tout est défini côté backend, puis importé dans le client.

Je vous montrerai à la fin qu’il est possible avec à peu près tous les frameworks client (Flutter, React, Vue, ...) de consommer plus simplement un backend décrit avec Swagger.

 

Démonstration

Nous allons voir ensemble, à travers un petit exemple frontend Angular et backend Nestjs comment utiliser Swagger au mieux. 

 

Partie 1 : Décrire son backend avec Swagger

Voici un petit controller qui contient 4 endpoints très simples pour cette démo:

  • 2 GET
  • 1 POST
  • 1 DELETE

Précisions: 

Les décorateurs lignes 12, 13 et 14 sont des annotations qui vont permettre de décrire notre endpoint. On précise d’abord qu’il va retourner un code status 200 et son body sera de type “Image”, ensuite on y ajoute une petite description et enfin on précise que cet endpoint attend en entrée un Query Param qui se nomme “id”.

 

Partie 2 : Mise en route du backend

Une fois nos endpoints correctement annotés, on peut lancer notre backend sur http://localhost:3000/ 

Swagger va nous générer 2 choses : 

On retrouve nos 4 endpoint décrits plus haut, on peut voir de quel type ils sont, et leur chemin. Si l’on clique sur l’un deux, on peut voir plus de détails, notamment les paramètres attendus en entrée et en sortie.

Un petit plus, que je trouve très intéressant, on a la possibilité de déclencher un endpoint directement depuis cette interface graphique. Cela permet, dans un environnement de test, de pouvoir déboguer plus intuitivement qu’en utilisant le traditionnel Postman.

 

Ce fichier JSON reprend les informations visibles sur l’interface graphique. Et c’est lui qui va nous intéresser dans la seconde partie de cet article où nous allons pouvoir exploiter ces informations.

 

 

Partie 3: Génération des services Angular

C’est maintenant qu’intervient notre petit module miracle : ng-openapi-gen : https://www.npmjs.com/package/ng-openapi-gen

Nous allons pouvoir générer automatiquement des services et méthodes prêtes à l’emploi pour consommer notre API avec Angular.

$ npm install -g ng-openapi-gen

$ ng-openapi-gen --input my-api.json --output output-folder

  1. On installe notre module de façon global, afin de pouvoir l’utiliser en ligne de commande
  2. On lance la commande de génération des fichiers avec 2 paramètres. Le premier (--input) précise le fichier d’entrée, on suppose qu’on a stocké le fichier JSON vu plus haut, dans le répertoire courant sous le nom de my-api.json. Le deuxième (--output) précise le répertoire de sortie.

Voici le résultat :

 

Partie 4 : Utilisation des service générés

Nous allons maintenant voir ensemble comment utiliser concrètement ce que nous venons de générer avec Angular :

Après avoir injecté au niveau du constructeur le service généré plus haut, on peut observer l’autocompletion proposée. On retrouve nos 4 endpoints sous forme de méthodes, typés fortement.

Plus besoin de saisir manuellement l’url complète de l’endpoint, au risque de faire une faute de frappe. Plus besoin de définir côté front, en doublon le modèle renvoyé dans le body.

 

Pour conclure

  • Efficacité

Le fait de mettre en lien notre backend et notre frontend grâce à Swagger, nous permet de gagner en efficacité. 

Il peut être intéressant de régénérer à chaque lancement du client en mode dev, la régénération des services. Ainsi, si des propriétés sont modifiées d’une classe, le compilateur du client va automatiquement nous alerter et nous prévenir des potentielles erreurs.

Cela nous permet de ne pas passer au travers, et de détecter les erreurs au plus tôt.

On gagne également en efficacité, dans le sens ou la communication backend -> frontend est amélioré, dans le cas où ce sont 2 équipes distinctes qui en sont en charge.

  • Universel

Je vous le disais en introduction, pour à peu près chaque framework client, on retrouve l’équivalent de ng-openapi-gen, afin de consommer au plus simplement l’API décrite avec Swagger, dans le framework respectif.

Quelques exemples : 

Pour les autres frameworks, que j’ai oublié, il suffit de faire une recherche dans google :  “<le-nom-du-framework> openapi”     

Florian Pascouau.

Restez informés

Recevez chaque mois nos dernières actus techs et événements à venir.

Social

Un peu de lecture

SFEIR est AWS Authorized Training Partner

SFEIR est désormais Training Partner de AWS

Actualités, Communiqués de presse

SFEIR est désormais Training Partner de AWS   SFEIR accède à l’AWS Training Partner Program visant à former les professionnels de l’informatique au cloud AWS en France.   Paris, le 15 Novembre 2022 – SFEIR, société de conseil en stratégie...

Lire la suite

Partenariat SFEIR Scaled Agile

SFEIR et WEnvision signent un partenariat stratégique avec Scaled Agile pour développer son offre de formation

Actualités, Communiqués de presse

SFEIR et WEnvision signent un partenariat stratégique avec Scaled Agile pour développer son offre de formation PARIS, le 7 novembre 2022 - le Groupe SFEIR, cabinet indépendant de conseil et d’expertise technologique  annonce un partenariat avec Scaled Agile éditeur du...

Lire la suite

Nomination de Renaud Chevalier

La nomination de Renaud Chevalier au poste de Consulting Director - Product & Organization au sein de WEnvision

Actualités, Communiqués de presse

La nomination de Renaud Chevalier au poste de Consulting Director - Product & Organization au sein de WEnvision   Renaud Chevalier rejoint l’équipe fondatrice de WEnvision au poste de Consulting Director - Product & Organization , venant renforcer la montée en puissance du...

Lire la suite

Rejoignez-nous

Première communauté Dev d’Europe
600 développeurs unis par la passion

Parlez à un expert

Social

Contact