Un Swagger sans l’écrire | API documentation generator

Partager sur twitter
Partager sur linkedin
Partager sur facebook
Partager sur reddit
Partager sur email
Partager sur telegram
Partager sur whatsapp

Un Swagger c’est bien, sans avoir à l’écrire c’est mieux. Et si vous pouviez automatiser vos spécifications ?

“On a pas eu le temps de documenter cette API”, ”la spécification de cet endpoint n’est pas à jour”, “Tu regarderas, on a ajouté tels champs et modifié tels autres”. On ne compte plus les occurrences de ces petites phrases entendues au sein des équipes de développeurs. C’est à la fois leur faute, et si vous en êtes les managers, ou les clients, la vôtre. La faute au temps toujours trop court, au temps passé sur des sujets chronophages, à se demander s’il ne faudrait pas ajouter tels champs ou tel autre. La faute aussi voire surtout à Swagger et OpenAPI, outils reconnus dans la communauté des développeurs, mais à condition que ce ne soit pas votre tour d’écrire un joli fichier texte aux règles aussi nombreuses que complexes, où même l’indentation compte.

Et on ne vous parle pas de cycle de vie, de Design Pattern, d’homogénéité. Le langage Swagger est puissant, permet de décrire beaucoup de choses, mais sa courbe d’apprentissage et son coût de maintenance en font un vrai obstacle.

Certains avaient pris le parti de dire qu’un Swagger se génère à partir du code, et c’est en effet une possibilité. Attention en cela qu’elle prive de la possibilité de générer un MOCK automatiquement, de paralléliser des développements, et donc conduit à se heurter aux problèmes de temps, encore lui.

Mais le principal inconvénient du Swagger en est sans doute l’usage limité : il ne sert qu’aux développeurs. Parce qu’un Swagger ne parle pas au département marketing, aux clients, aux décideurs, le voilà désavoué avant même de s’être imposé en entreprise, qui a besoin de ce développement rapidement “juste cette fois-ci”. Si la dette technique n’en finit rarement de grandir, le besoin en documentation, lui, ne faiblit pas. Taille importante des équipes, nombre d’interlocuteurs, pérennisation des développements en prévisions de turn-over ou en période de consolidation des actifs, les bonnes raisons ne manquent pourtant pas. Et pourtant, la documentation est rarement là et de bonne qualité. Or ce qui n’est pas documenté est à moitié perdu, difficilement maintenable et valorisable sur le long terme. Difficile dans ces conditions également de tester ce qui n’est pas spécifié complètement.


On ne le dira jamais assez chez APIZR : Une API non documentée, c’est comme regarder un dictionnaire avec les mots dans le désordre ! 

Avec un peu de recherche et de courage, on trouve, mais au prix d’un temps que l’on a rarement.

Voici les raisons qui nous ont poussés chez APIZR à voir le problème autrement. Parce qu’un Swagger c’est bien mais sans avoir à l’écrire c’est mieux, nous avons voulu passer du temps sur ce qui a une plus-value : le design. Passer du temps pour savoir quelles sont les données métiers que les utilisateurs finaux vont vouloir voir ou manipuler, voilà le point de départ essentiel d’un design d’API.

Un mind-map en lieu et place de spécifications

mo du produit APIGrow

Parce que tout le reste peut s’en déduire, être mis à jour en quelques instants. Dites Adieu aux fichiers yaml, et même aux refcards. Définissez une fois pour toutes les règles de nommage et le template de votre entreprise et APIGrow© se charge de transformer vos dessins de réunion de brainstorming en spécifications complètes, uniformes, dynamiques et maintenables. Réunion de lancement terminée? le développement de vos APIs peut déjà commencer… Un champ à ajouter lors d’une phase de recette? Cela n’implique plus qu’une petite modification de mindmap, et vos spécifications sont automatiquement re-générées de façon homogène. 

Peuvent en découler la génération automatique de MOCK, de scénarios de tests unitaires. Voire celle de vos APIs si le coeur vous en dit.

En savoir plus : contactez nous

Testez APIGrow gratuitement

Victor Dusautois

Victor Dusautois

Laisser un commentaire

L'auteur

A propos d'Apizr

APIZR, accompagne les entreprises dans l'APIsation de leur système d'information, l'ouverture de leurs données afin de rendre plus agile les projets (+ de 50% des temps projet sont "perdus" à rendre accessible le SI) et de rationaliser les développements (nos APIs sont réexploitables entre vos projets mobile, site, objets connectés, etc...)

Nos dernières publications

Recevez les nouveautés Apizr

Nos coordonnées

Nous contacter