INTRODUCTION

Actuellement, lorsque nous développons des apis Asp.Net Core, nous utilisons habituellement Swagger afin de bien documenter, en utilisant le format Open API Specification (ex Swagger), chaque endpoint de notre api. Pour ce faire, les packages NuGet comme Swashbuckle.AspNetCore ou bien Nswag.AspNetCore et quelques configurations initiales sont nécessaires.

Grâce à l’interface utilisateur SwaggerUI ainsi générée automatiquement, chaque point d’entrée est détaillé avec un exemple de structure des paramètres à envoyer, ce que la méthode renvoie ou encore le format des résultats retournés. Il devient ainsi plus facile pour un utilisateur de les tester directement via cette interface.

Toutefois, nous avons encore quelques lignes de code à écrire pour pouvoir consommer notre api depuis notre application cliente. Pour éviter de les coder à la main et faciliter l’appel à nos points d’entrée, NSwagStudio nous offre un moyen facile de générer le code client correspondant à notre Api REST. Il existe d’autres outils ou solutions pour atteindre cet objectif, notamment des solutions évoluées SaaS de publication et de gestion en ligne des API comme les services SwaggerHub ou Azure API Management ; mais dans cet article, nous allons nous concentrer plus sur l’utilisation de cet outil simple.

A la fin de cet article, vous saurez désormais comment appeler directement vos apis depuis une application Angular.

PRE-REQUIS

Evidemment, nous aurons besoin d’une api REST ASP.Net Core existante, que nous aurons déjà configurée en amont et que nous pouvons appeler à partir d’un navigateur. Nous n’allons pas voir ici comment créer un Api AspNet.Core mais nous supposons que vous savez déjà le faire ;)

Nous prendrons comme exemple une api REST appelée Kindergarten. Cette api n’aura qu’une seule méthode de type Get : api/class/list qui va renvoyer la liste de toutes les classes disponibles ainsi que les élèves d’une école maternelle.

En cliquant sur le lien montré par la flèche, nous avons les détails de l’api. Copiez l’url de la spécification Swagger : https://localhost:5001/swagger/v1/swagger.json

Pour pouvoir vérifier plus tard, voyons un bout des résultats que nous a retournés la méthode list :

CONFIGURATION DE NSWAGSTUDIO

Commençons par installer NSwagStudio : il s’agit d’une application Windows nous permettant de générer le code client nécessaire pour consommer une Api REST documentée avec Open API Specification(swagger). L’outil est disponible en téléchargement ici

Son interface permet de choisir entre générer des codes clients en C# ou en Typescript. Etant donné que nous avons une application cliente Angular comme exemple, nous verrons uniquement la génération de code en Typescript.

Pour commencer, ouvrez NSwagStudio et faisons quelques configurations. Commençons par la partie gauche de l’interface :

1– Pour le Runtime, choisir NetCore31

2– Ouvrir l’onglet Open API/Swagger Specification,

3– Dans la case Spécification URL, mettre l’url de documentation de l’api : https://localhost:5001/swagger/v1/swagger.json

4– Cliquer sur le bouton Create local Copy pour créer une copie locale du contenu du swagger.json

Continuons maintenant à configurer dans la partie droite de l’interface :

5– Cocher TypeScript Client pour avoir du code client généré en Typescript.

6– Parmi les deux onglets horizontaux, ouvrir l’onglet Typescript Client. Dans le cas où vous auriez à générer du code C#, l’onglet correspondant sera affiché en-dessous.

Une fois sur cet onglet, nous aurons deux sous-onglets affichés dans le vertical: Settings et Output. Les étapes suivantes seront à faire dans le premier sous-onglet Settings

7– Comme Template, choisir Angular

8– Cocher Use Angular 6 Singleton Provider

9– Pour Operation Generation Mode, sélectionner MultipleClientsFromFirstTagAndPathSegments

Nous avons fait les bases de la configuration. Des besoins spécifiques auront surement besoin de plus de configurations.

Pour générer le code client, nous avons deux boutons :

• Generate Outputs pour afficher le code généré dans le sous-onglet Output, afin de le lire ou de le copier/coller.
• ou Generate Files pour générer et sauver immédiatement dans le fichier spécifié dans la case Output file qui se trouve tout au-bas de l’interface.

Dans notre exemple le chemin output file pointe sur le fichier de composant Typescript que nous devons créer dans l’application KindergartenApp.

UTILISATION DEPUIS UNE APPLICATION ANGULAR

Maintenant que le code client de notre api a été généré, nous pouvons maintenant appeler la méthode depuis notre application sans avoir à coder les appels http.

Nous n’allons pas voir comment créer une application Angular, nous supposons que vous savez déjà le faire ;)

Voyons un peu le code que NswagStudio nous a généré dans notre application cliente KindergartenApp :

Depuis un service que nous aurons créé par ailleurs, nous appelons la méthode list pour avoir la liste de toutes les classes.

Essayez de lancer votre application après avoir appelé votre méthode de service depuis votre composant angular :

Il est nécessaire de configurer l’adresse de base de l’api via API_BASE_URL dans votre app.module.ts comme ci-après :

En effet les urls sont généralement différentes d’un environnement à un autre. Dans notre petit exemple, nous configurons cela par environnement via le fichier environnement.ts :

Quand vous lancerez votre application, vous vous apercevrez que vous aurez une erreur CORS sur le navigateur :

Access to XMLHttpRequest at ‘https://localhost:5001/api/class/list’ from origin ‘http://localhost:4200’ has been blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.

Afin d’y remédier si ce n’est déjà fait, retournez dans le fichier Startup.cs de votre api afin d’autoriser l’url de votre application cliente à accéder à l’api.

Sans oublier l’option associée .UseCors dans la méthode Configure :

Maintenant, quand vous actualisez la page de votre application cliente sur le navigateur, vous aurez la liste qu’a retournée votre api. Dans cet exemple, j’ai un peu modifié le projet Angular de base pour pouvoir afficher toutes les classes de Kindergarten.

CONCLUSION

NSwagStudio est un outil qui fait gagner du temps dans le développement de nos applications clientes. Il est facile à configurer et à utiliser. Il permet d’éviter de coder à la main les requêtes http nécessaires. Mais il ne faut pas surtout oublier que cela est uniquement possible si notre api est conforme et expose bien une spécification Open API(swagger) Specification (grâce à ses endpoints Swagger).