Les développeurs d’IBM veulent simplifier la documentation d’API
IBM a dévoilé un nouvel outil open source, pour faciliter la documentation d’API écrites en NodeJS et dans d’autres langages prochainement. L’équipe derrière le projet promet un gain de temps considérable.
La documentation d’API RESTful n’est généralement pas une partie de plaisir. Il faut constamment imaginer qu’elle sera utilisée par les équipes en interne et potentiellement par des partenaires d’une entreprise.
Des spécifications comme OpenAPI doivent normalement aider à simplifier cette démarche, mais encore faut-il savoir maîtriser les nombreuses facettes de ce projet open source dont la très complète boîte à outils Swagger. De plus, le code est de nature changeante, soumis à des modifications régulières, voire constantes. C’est en tout cas en s’appuyant sur des arguments similaires qu’IBM a présenté le projet (sous licence Apache V2) OpenAPI Comment Parser.
« Lorsque la spécification OpenAPI se trouve dans le code, les développeurs sont beaucoup plus susceptibles de la tenir à jour au fur et à mesure que leur code évolue. »
Nicholas BourdakosDeveloper Advocate, IBM Watson
« L’objectif du parseur de commentaires OpenAPI est de donner aux développeurs un moyen de générer cette spécification OpenAPI à partir de commentaires alignés sur leur code. Lorsque la spécification OpenAPI se trouve dans le code, les développeurs sont beaucoup plus susceptibles de la tenir à jour au fur et à mesure que leur code évolue », écrit Nicholas Bourdakos, Developer Advocate chez IBM Watson, dans un article de blog.
Avec la librairie OpenAPI Comment Parser, IBM entend générer une documentation plus fragmentée, mais plus précise et, en principe, continuellement à jour à partir des commentaires des développeurs.
OpenAPI Comment Parser s’appuie sur Docusaurus, un projet justement conçu pour simplifier le maintien et les mises à jour des documentations d’API. Les deux outils permettent de générer les informations en s’appuyant sur le code associé. Les développeurs n’ont pas à créer eux-mêmes un fichier YAML, ils utilisent les syntaxes YAML ou JSDoc (pour NodeJS) afin d’écrire leurs commentaires. Le Parser les interprète pour générer la documentation dans un format compris par OpenAPI.
La librairie intégrée est conçue pour NodeJS, mais le CLI serait compatible avec tous les langages qui utilisent la mise en page ainsi que les balises types de JSDoc. L’équipe derrière le projet open source prévoit d’accroître la compatibilité avec différents langages de programmation dans les mois à venir.
Réduire le temps de lecture et d’écriture de la documentation
Selon Nicholas Bourdakos, cette fragmentation permettrait de ne pas manipuler de gros volumes d’information OpenAPI et donc de réduire significativement le temps passé à rédiger les commentaires et la documentation. « En moyenne, il a été démontré que ce nouveau format réduit de 50 % la quantité de spécifications à rédiger », indique-t-il dans son article.
« En moyenne […] ce nouveau format réduit de 50 % la quantité de spécifications à rédiger. »
Nicholas BourdakosIBM Watson
Surtout, cela permet de générer de la documentation directement depuis le code source sans utiliser plusieurs outils et d’obtenir le même niveau d’information avec moins de code. Selon Nicholas Bourdakos, la documentation est aussi plus facilement accessible même quand il n’y a pas de front end et accélérerait donc les phases de test. De la sorte, que ce soit depuis un IDE ou une page Web, les développeurs bénéficient de la même documentation et n’ont pas à jongler avec plusieurs fichiers ou outils pour comprendre le fonctionnement d’une API.
SmartBear, l’éditeur de Swagger et créateur de la spécification OpenAPI propose un système similaire pour Java avec Swagger Inflector, mais la documentation créée s’appuie sur des commentaires plus fournis, plus longs à rédiger. La plupart des outils gratuits ou payants de Smartbear doivent avant tout faciliter la création et la documentation d’API selon les standards de la spécification OpenAPI. Avec Comment Parser, IBM s’inscrit bien dans cette droite lignée tout en imposant son style de commentaires. Cependant, le projet n’en est qu’à ses débuts et reste à savoir si la librairie séduira en dehors de l’écosystème NodeJS pour lequel elle est originellement conçue.
