Documentation Open-API et génération de code automatique

Bonjour,

Aujourd’hui quand on parle génération automatique du code, on pense un peu trop vite à ChatGPT et l’IA pour bosser à notre place… mais on n’a pas attendu l’IA pour avoir des outils de génération de code :slight_smile: Le 1er exemple c’est composer qui nous génère l’auto-loader pour toutes les librairies importées à l’installation.

Aujourd’hui je voudrais parler de Open-API : c’est un formalisme pour décrire les API au format yaml (ou json les 2 sont possibles mais j’aj choisit yaml). Je pensais que ce formalisme était réservé aux API de type REST-API, c’est une convention où le type de requête HTTP : PUT / GET / POST / DELETE doit correspondre à l’opération CRUD (Create / Read / Update / Delete) que l’on veut effectuer en base.

Par exemple une requête http://myjeedom.url/api/v1/eqlogic/42 me permet:

  • si c’est une requête GET, de lire le eqLogic id=42 en base
  • si c’est DELETE, on le supprime!
  • si c’est POST ou PUT, alors il faut enricher le body de la requête pour enregistrer cet objet en base…

ça c’était pour la partie REST / RESTFULL de l’API, mais j’ai appris par hasard (en discutant avec chatGPT!) qu’on peut aussi bien formaliser une API au standard RPC sous ce format Open-API. Et ça, c’est génial ça ouvre plein de possibilités, comme, par exemple générer automatiquement une documentation de type swagger, voire qu’on peut même tester online! Et aussi, il existe des outils pour traiter la définition de l’API pour générer le code, les entitées (schéma) et les interfaces voire même certaines implémentations. Et ceci dans de nombreux languages!

Je l’ai donc fait, j’ai formalisé l’API Json-RPC de Jeedom au format Open-API, ce n’était pas simple parce que, autant pour les paramètres d’entrée de l’API je pense que c’est complet, autant pour les réponses il n’y a rien du tout. On peut supposer que ça reprend le schéma de la bdd à première vue, mais je me suis juste basé sur quelques tests avec Postman pour décrire quelques réponses pour le moment.

Voici donc le yaml qui décrit l’API Json-RPC

Et, après une moulinette automatique (ici un workflow github) on génère cette documentation dite swagger:
https://pifou25.github.io/jeedom-ui/

C’est un bon début, mais on peut aller plus loin :slight_smile: l’outil openapi-generator permet de générer dans le language de notre choix tout ce qui est décrit dans ce fichier Open-API, je l’ai fait pour l’exemple en typescript (pour un frontend Angular) c’est tout ce qui est ici dans /angular-client
La liste des générateurs disponibles est longue comme le bras (php python javascript java dart android et j’en passe) c’est ici : Generators List | OpenAPI Generator

Et ensuite ? Je propose d’ajouter ce fichier yaml dans la doc, et ça serait bien d’avoir le swagger disponible aussi, soit dans la doc ou bien directement dans le core Jeedom pour pouvoir tester online sa propre configuration.

Aussi, ça me démange de faire une version RESTFULL de l’API, une fois le fichier yaml créé il ne manque pas grand-chose pour connecter ce qui est automatiquement généré sur les méthodes existantes du core…

1 « J'aime »