Mise en place de Redoc

[fchabouis]

On aimerait bien que la documentation de notre API vive au même endroit qu'elle, pour la garder bien à jour. J'installe ici drf-spectacular qui permet de servir une doc Redoc (front pour OpenAPI) pour DRF.

La doc est disponible à l'adresse /api/alpha/schema/redoc et le schema OpenAPI à l'adresse /api/alpha/schema

J'ai documenté uniquement le endpoint "liste des bâtiments", car je considère cette PR comme la mise en place de l'outil. Nous pourrons compléter la doc au fur et à mesure et communiquer sur elle quand elle sera complète.

[pauletienney]

Je viens de le faire tourner sur ma machine. Je pense que générer un schéma OpenAPI en étant au plus près du code a un intérêt pour nous et in fine pour le lecteur mais j'ai un vrai problème avec Redoc qui en l'état est très austère et même assez peu clair je trouve. J'imagine qu'on peut le customiser.

Sinon, il peut y avoir la solution d'utiliser https://redocly.com/ (fait par les mainteneurs de Redoc si je ne me trompe pas). Ils proposent un thème de base sensiblement plus clair et une variété d'outils de customisation.

Edit : après vérification, l'aspect des blocks openAPI de gitbook sont pas mal. Il faudrait tester comment se passe l'update des blocks sur gitbook quand le schema change.

[fchabouis]

Oui je suis d'accord que c'est pas hyper beau, ça peut nous permettre de commencer à remettre la doc à jour, puis de trouver une autre manière plus jolie de l'afficher par la suite.