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

pifou · Juin 18, 2025, 8:20

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

github.com

pifou25/jeedom-ui/blob/open_api/public/api/jeedomApiRpc.yaml

openapi: 3.0.3
info:
  title: Jeedom JSON-RPC API
  description: |
    Spécification OpenAPI pour l'API JSON-RPC de Jeedom. [Spécifications Json RPC](http://www.jsonrpc.org/specification)
    
    Voici un exemple d’utilisation de l’API. Pour l’exemple ci-dessous j’utilise cette classe php qui permet de simplifier l’utilisation de l’api.
    
    **Récupération de la liste des objets :**
    ```
    $jsonrpc = new jsonrpcClient('#URL_JEEDOM#/core/api/jeeApi.php', #API_KEY#);
    if($jsonrpc->sendRequest('jeeObject::all', array())){
        print_r($jsonrpc->getResult());
    }else{
        echo $jsonrpc->getError();
    }
    ```
    
    **Exécution d’une commande** (avec comme option un titre et un message)
    ```

This file has been truncated. show original

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 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…