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.