Développement d'un support de documentation API à destination des équipes techniques, sous la forme d'un CMS administrable.
Général • Brief
OCEAN propose une API pour son service de geolocalisation de flotte automobile, pour laquelle il m’a été demandé de créer un support de documentation des webservices. De par divers contraintes, c’est la forme d’un site CMS qui a été retenu.
Basé sur le CMS Grav et un thème développé dans ce but précis, cet outil permet de décrire des requêtes API de manière semi-complexe, tout en proposant une administration simple et accessible.
Documenter des
requêtes API
via un site CMS
Général • Choix de l'outil
Après avoir envisagé plusieurs outils avancés de génération d’API à partir du code source (API Blueprint, APIDocs, DapperDox…) leur usage s’est avéré trop technique pour l’équipe communication, amenée également à intervenir sur le support final.
En prenant en compte ces contraintes d’administration et d’édition, mon choix s’est finalement porté sur le CMS Grav.
Relativement récent, fonctionnant sans base de données, Grav est simple d’utilisation et ne s’éparpille pas à travers de multiples fonctionnalités. Extensif et facile à personnaliser, il s’est avéré idéal pour un usage centré sur un but de documentation. Les fonctions de description d’API ont été apportées par un thème développé à cet escient.
Technologies
Yaml
Pour définir les types de contenus et les champs associés en back-end
Twig/SCSS
Pour créer et styliser les modèles de page en front-end
Symfony
Pour gérer l’architecture globale relative à Grav et certaines fonctionnalités
Pages • Chapitre
Structure
simple
En prenant pour base un thème simple à fonction de documentation, j’en ai étendu les fonctionnalités via un thème enfant pour l’adapter au contexte technique de la description d’API. Pour ce faire, j’ai créé différents modèles de page : simple, chapitre, webservice & requête.
La navigation est organisée en chapitres, représentés dans un menu/table des matières sur la gauche. Il est également possible de naviguer d’une page à l’autre via les flèches latérales.
Le contenu du site est principalement constitué de descriptions des requêtes API, regroupées en chapitres par type de webservice.
Pages • Requête API
Sujet
technique
Les requêtes API peuvent comporter un important nombre d’informations. Elles sont divisées en 3 sections principales :
- la description de la requête
- ses paramètres d’entrée
- les réponses retournées, ainsi que l’objet renvoyé et sa description paramètre par paramètre
Ces informations techniques à destination des développeurs sont normées et se doivent donc de suivre un certain schéma imposé dans leur rédaction et leur présentation visuelle
Description des paramètres d’entrée
Description de l’objet retour
Pages • Simple
Back-Office • Description de requête
Requêtes,
objets et
imbrication
La description de requêtes API peut être complexe : des paramètres d’entrée des requêtes aux réponses et objets de retour, il s’agit pourtant de fournir des préconisations détaillées pour un usage technique. De plus, il peut être fréquent de rencontrer des objets imbriqués, et ce jusqu’à un certain nombre de niveaux.
Cela se traduit sur le modèle en back-office par des groupes de champs prédéfinis, amovibles et multipliables, permettant de décrire ce schéma de manière normée, tout en évitant un certain nombre d’erreurs liées à la rédaction. En dehors des noms de variables, descriptions, l’utilisateur est guidé dans son choix via des menus déroulants ou cases à cocher.
L’imbrication dynamique est rendue possible de deux manières : sur un nombre de niveaux limités lors de l’édition d’une réponse, ou en créant des modèles d’objets. Référençables en tant que paramètres dans les réponses ou d’autres objets, is étendent à l’infini le niveau d’imbrication possible, tout en facilitant l’édition d’objets récurrents dans l’API.
Définition d’un objet retour complexe accompagnant une réponse 200 sur une requête API