add swagger-ui documentation

[pifou25]

Description

le swagger-ui tel que présenté sur le community
https://community.jeedom.com/t/documentation-open-api-et-generation-de-code-automatique/141421
le but est d'avoir la doc au plus proche du code, ainsi je propose de l'héberger et l'avoir disponible localement:
http://localhost/docs/swagger-ui/index.html (le résultat ici https://pifou25.github.io/jeedom-ui)
J'ai donc supprimé le .htaccess dans /docs et modifié celui de racine pour autoriser l'accès. (Toute la doc dispo en format markdown mais bloquée par le .htaccess ça n'est pas très utile)

Mais peut-être vous préférez héberger la doc uniquement sur le repo documentation et mettre ce swagger à côté ou à la place de l'existante https://doc.jeedom.com/fr_FR/core/4.1/jsonrpc_api ?

Suggested changelog entry

swagger-ui for Json-RPC API

Related issues/external references

Fixes #

Types of changes

• Bug fix (non-breaking change which fixes)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
  • This change is only breaking for integrators, not for external standards or end-users.
• Documentation improvement

PR checklist

• I have checked there is no other PR open for the same change.
• I have read the [La ligne directrice pour contribuer à ce projet / Contribution guidelines for this project).
• I grant the project the right to include and distribute the code under the GNU.
• I have added tests to cover my changes.
• I have verified that the code complies with the projects coding standards.
• [Required for new sniffs] I have added MD documentation for the sniff.

[kwizer15]

Je trouve cette initiative très pertinente ! L’idée d'avoir Swagger UI pour l’API JSON-RPC est vraiment bonne.
Par contre j’ai quelques doutes sur la suite :

• Maintenabilité : Comment tu as créé le YAML ? Si c’est fait à la main, ça va vite devenir galère à maintenir : à chaque modif de l’API il faudra penser à mettre à jour la doc. Et on va se retrouver avec deux docs à maintenir (celle-ci + doc.jeedom.com).
• Sécurité : Les modifs sur les .htaccess me font un peu tiquer, on doit être sûr de ne pas exposer des trucs sensible.
  Tu as pensé à automatiser ça ? Avec swagger-php par exemple qui génère la doc directement depuis le code ? Ça éviterait les problèmes de syncro et ce serait beaucoup plus maintenable sur le long terme.

[pifou25]

Maintenabilité : il y a 2 sujets

• pour moi la page existante pour l'API devient redondante, le swagger peut totalement remplacer celle-ci, quitte à rajouter un peu plus de commentaires / descriptions dans le yaml.
• Par contre, côté code ça reste aussi redondant, mais la théorie voudrait qu'on adapte pour mettre une partie du code auto-généré, à partir du swagger : ainsi lorsqu'on veut faire évoluer l'API on va d'abord directement modifier le swagger, puis générer le code modifié correspondant (donc principalement les entités et interfaces) et ensuite si besoin on adapte l'implémentation.

Sur la partie sécurité je n'ai fait que ouvrir l'accès au répertoire /docs donc rien de sensible. Mais je pourrais aussi créer un nouveau répertoire /swagger pour ne pas toucher à l'existant et laisser la doc inaccessible, ça se discute.

[kwizer15]

Je te rejoint sur la premier point.

Pour le second, c'est relativement claire avec tes explications. Je pense qu'il faudrait a minima une doc pour décrire la marche à suivre. Et éventuellement une note dans la phpdoc de l'api avec le lien.

Pour la sécurité, je ne pense pas non plus que ce soit critique, mais c'est toujours préférable de le signaler.

[Mips2648]

Concernant l'aspect sécurité et d'ouvrir l'accès, je ne suis pas d'accord.
Ca reste du code à maintenir, y a du js, une faille peut arriver et servir de rebond et cette partie est inutile dans plus de 90% des installations.
La surface d'attaque doit toujours est réduite au minimum, là on ouvre parce que "c'est plus simple". Ce n'est pas la bonne approche selon moi.
Soit:

• Le swagger doit être hébergé sur un site propre.
• cela ne doit être ouvert que si "installation en mode dev" (concept qui n'existe pas sous jeedom)

Mais sur une installation de "prod", ca doit être fermé.

[pifou25]

Ok je comprends ton argument, c'est vrai je pourrais laisser le .htaccess pour barrer l'accès par défaut, et charge à celui qui veut accéder à cette doc en local de supprimer ce fichier.

Après, c'est quand même du code entièrement généré, il est maintenu par une équipe, on a juste à le regénérer + commit lorsqu'il y a des mises à jours sur leur repo (et ils sont plus réactifs que jeedom) (haha elle était facile celle la) et on pourrait aussi faire un workflow pour automatiser cette mise à jour.

Mais d'un autre côté j'ai fait la même PR sur le repo doc de jeedom ici où il a toute sa place. Je comprendrais tout à fait un ref-flag ici et qu'on ferme cette PR. Mais dans ce cas, à quoi sert le rep docs dans le core ? Autant tout supprimer non ? On n'y a accès d'aucune manière ?