Cet article fait partie de notre guide: API : l'ouverture des SI dans un monde de microservices

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

Les APIs sont certes devenues une composante clé des architectures logicielles, les développeurs peinent encore à les façonner. En cause : l’écart entre la publication de la documentation et celle des spécifications. Brad Irby nous fait part d’un outil qui permet d’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.

Instagram API code
Figure 1 : L’API d’Instagram comme exemple

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.

defined paths
Figure 2 : Un path complet

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).

Media definition
Figure 3 : Une vue partielle de la définition Media

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.

auto generated documentation
Figure 4 : La documentation est générée automatiquement

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.

generate server
Figure 5 : Utiliser les options « Generate Server » et « Generate Client »

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.

Pour approfondir sur API

Close