Générer un sdk pour consommer vos API Web avec Visual Studio

Après avoir vu une des sessions de la Build 2015, je me suis dit que je devais absolument faire un article sur une des choses que j’ai découvert durant la visualisation de cette session. Au cours de cet article je vais donc vous montrer comment générer un sdk pour pouvoir interagir avec une Web API que vous aurez développé, ou pas d’ailleurs.

NB : Pour pouvoir mettre en place ce qu’il est décrit dans cet article, il vous faut avoir au minimum la version 2.5 du sdk Azure sur votre poste.

Pour commencer

Le point de départ est une solution contenant un projet de type Web API, vous pouvez partir de n’importe quel projet de ce type ou vous basez sur l’application exemple qui se trouve ici https://github.com/dmoisa971/SdkGeneratorSample. Au niveau de l’application exemple j’ai un projet Web API contenant une Web API permettant de gérer des Customers, des Orders et des Articles.

Ensuite j’ai un projet Model de type Portable class, qui contient l’ensemble des entités métier exposée par mon API.

Mise en place de Swagger

Pour pouvoir générer notre sdk nous allons dans un premier temps avoir besoin d’un fichier de metadata décrivant la structure de notre API, et pour se faire nous allons utiliser le framework Swagger.

Swagg.. quoi ?

Swagger est un framework permettant en autre de générer un fichier de metadata d’un service REST, il permet aussi de générer une page de documentation de notre API contenant aussi tout ce qu’il faut pour pouvoir effectuer des tests de notre API, depuis une page Web.

Pour plus d’informations, vous pouvez visiter l’URL suivante : http://swagger.io/

Pour pouvoir mettre en place Swagger au niveau de notre Web API il suffit de rajouter un package nugget qui va se charger de faire le nécessaire. Le package en question se nomme swashbuckle. Vous pouvez donc à partir de votre gestionnaire de packages préféré, faire une recherche sur ce package et le rajouter à votre solution.

blog ai3 AddSwashbuckle-300x157 Générer un sdk pour consommer vos API Web avec Visual Studio

Dès votre opération terminée, lancer en mode debug votre Web API, et allez à l’URL suivante :

http://<hostName>/swagger

Vous allez alors voir apparaître devant vos yeux éblouis, une page contenant l’ensemble des informations concernant votre API, accompagnées des fonctionnalités de tests pour chacune des opérations exposées par votre API, comme le montre l’image ci-dessous.

blog ai3 swagger-300x207 Générer un sdk pour consommer vos API Web avec Visual Studio

 

Ensuite si vous allez à l’URL http://<hostName/swagger/docs/V1, vous allez arriver sur un document au format JSON. C’est ce document qui être utilisé dans un second temps pour la génération de notre sdk.

Sauvegardez le contenu de ce fichier sur votre disque est arrêter le mode debug. Nous allons maintenant passer à la seconde étape durant laquelle nous allons générer notre sdk.

blog ai3 swaggerDoc-300x84 Générer un sdk pour consommer vos API Web avec Visual Studio

 

Génération du sdk

Afin de procéder à la génération de notre sdk, nous allons ajouter à notre solution un projet de type PCL, ceci afin de pouvoir utiliser notre sdk dans tout type de projet. Pour le nommage de ce projet je laisse libre cours à votre imagination.

Au niveau du projet supprimer le fichier Class1.cs généré lors de la création du projet.

Ensuite faire un clic droit sur le projet et choisissez l’option Ajouter -> Azure API App Client.

Au niveau de la fenêtre qui s’ouvre sélectionnez l’option Select an existing Swagger metadata file

blog ai3 AzureAppJsonSelection-300x177 Générer un sdk pour consommer vos API Web avec Visual Studio

Allez ensuite rechercher le fichier Swagger que vous avez sauvegardé lors de l’étape précédente.

Optionnellement vous pouvez aussi modifier le Namespace qui serait utilisé par votre sdk.

Quand tout est ok, cliquez sur OK et laissé la magie opérée. Au bout d’un laps de temps assez cours, vous allez voir un certain nombre de fichier ajouter à votre projet. Tous ces fichiers forment le sdk qui aura été généré pour vous, elle est pas belle la vie.

Ci-dessous vous pouvez voir un exemple du code qui est généré.

blog ai3 ProjectSdk-300x213 Générer un sdk pour consommer vos API Web avec Visual Studio

Mais comment est-ce possible ?

Dans cela rien de magique. La solution tient en un mot AutoRest.

AutoRest est un projet OpenSource permettant de générer des librairies clientes pour accéder à des services REST à partir des informations contenues dans un fichier au format Swagger.

A partir de la version 2.5 du sdk Azure la fonctionnalité d’appel de AutoRest a été ajouté à Visual Studio 2013, donc pas besoin de passer par la ligne de commande.

Pour plus d’information sur AutoRest, voici l’URL qu’il vous faut https://github.com/Azure/autorest

A noté que nous avons effectué notre génération pour du code C#, mais qu’il est tout à fait possible d’étendre les possibilités de génération. Au cours de la présentation vidéo, les cibles de générations étaient C#, Java, NodeJS, Python.

A vous de jouer

Maintenant que vous avez votre projet PCL contenant votre librairie cliente, vous pouvez utiliser celle-ci depuis tout type de projets WPF, Universal Apps, Web App, Xamarin …

Je vous laisse donc effectuer vos propres tests.

Conclusion

Voilà j’espère que ce petit article vous aura plu, pour voir la session en question voici l’URL : http://channel9.msdn.com/Events/Build/2015/2-628?format=html5.

 

David Moïsa.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.