API : comment automatiser la génération de code

Les APIs sont devenues très à la mode chez les développeurs. Mais en dépit de cette notoriété, ceux-ci doivent encore livrer bataille lorsqu’il s’agit de générer le code de l’API à cause de décalage entre la documentation et les demandes des chefs de produits. Dans cet article, je vous explique comment Swagger peut aider à maintenir une cohérence entre la documentation et le code, tout le long du processus de création d’une application.

Nous sommes d’accord sur le fait que les APIs sont un outil formidable, mais leur création reste encore une tâche qui n’est pas aisée. Il est nécessaire de prendre en compte nombre de détails. Mais il est également facile de perdre de vue certains de ces détails,  lorsque l’on traduit l’idée de départ d’un chef de produit dans une série de documents détaillant les specs, puis enfin en ligne de code. Grâce à Swagger, synchroniser les docs avec le code est devenu plus simple.

Swagger est un outil qui permet à quiconque disposant d’un minimum de compétences techniques de définir une API, de générer la documentation et même de générer le code. L’API est conçue au sien d’un éditeur en ligne via YALM, un langage XML très lisible. Celui-ci définit les endpoints, puis le format des paramètres d’entrée et de sortie des données, le niveau de sécurité que vous souhaitez implémenter. Et c’est prêt à être utilisé.

L’éditeur Swagger vous propose un exemple reposant sur l’API d’Instagram (Figure 1). Dans l’éditeur, sélectionnez « File », puis « Open Example ». D’autres exemples sont également disponibles.

Parmi les données de l’illustration ci-dessus, 8 paths ont été définis. On clique sur le petit triangle pour dérouler les nœuds. Lorsque vous en ouvrez un (Figure 2), on constate que cela nécessite GET HTTP. Vous pouvez consulter la description et constater qu’il requiert 3 paramètres. Si cela marche, il retourne un array d’objets.

De même, vous pouvez ouvrir la définition Media, et consulter les détails des propriétés de cet objet, comme les objets imbriqués (je ne montre qu’une partie de la définition dans la Figure 3).

Définir une API avec l’éditeur Swagger est pratique, mais pas plus facile que d’utiliser d’autres outils. Toutefois, dans le panneau de droite de l’éditeur, la documentation HTML est générée automatiquement. (Figure 4).  Elle apparait complète, agréable à lire et vous propose de tester les appels. En cliquant sur le bouton « Try this operation », vous pouvez saisir des paramètres, effectuer l’appel et observer le résultat.

Mais ce n’est finalement pas cela qui rend cet outil le plus indispensable. En vous appuyant sur les options « Generate Server » et « Generate Client » (Figure 5), vous pouvez générer le code pour publier et consommer cette API en plusieurs langages. A lui seul, cet outil de génération de code peut vous faire économiser des heures de programmations fastidieuses, sans parler du temps nécessaire à effectuer des modifications  tout le long du cycle de vie de votre API.  Vous pouvez également exporter le code pour créer un fichier en local et ainsi mieux contrôler les sources. Ce fichier peut aussi être publié pour que d’autres développeurs puissent intégrer rapidement vos données.

Rédiger une API est certes très utile mais aussi très chronophage. La concevoir avec Swagger et publier le fichier YAML peut faciliter vos processus internes et votre collaboration avec d’autres.