Création d'un support web de documentation d'API

Après avoir envisagé plusieurs outils avancés de génération d’API à partir du code source, leur usage s’avérait 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.

Logo Grav CMS

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 une fonction de documentation.

L'apparence générale

En me basant sur un thème simple à fonction de documentation, j’ai étendu les fonctionnalités pour l’adapter au contexte technique de la description d’API, via un thème enfant. Pour ce faire, j’ai créé différents modèles de page : simple, chapitre, webservice & requête.

Une structure simple

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.

Mais des contenus techniques

Les requêtes API peuvent comporter un important nombre d’informations. Elles ont 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 doivent donc suivre un certain schéma imposé dans leur rédaction.

Administration des contenus

La description de requêtes API peut être complexe : des variables fournies aux réponses et objets de retour, il s’agit pourtant de fournir des préconisations détaillées pour un usage technique.

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.

Imbrication des Paramètres & objets

Les paramètres pouvant être des objets regroupant eux-mêmes plusieurs paramètres, l’imbrication dynamique était à prendre en compte lors de la création de contenus.

Bien que rendu possible par l’ajout de code personnalisé l’imbrication reste toutefois limitée à un certain niveau pour faciliter l’édition.

Cependant, la possibilité de créer et référencer des modèles d’objets en tant que paramètres, pousse à l’infini le niveau d’imbrication possible sur les descriptions des paramètres de requêtes, tout en facilitant l’édition d’objets récurrents dans l’API. 

Définition de l’objet retour accompagnant une réponse 200 sur une requête API

Faites appel à
mes services !

Vous avez des besoins en graphisme ou conception web ? Échangeons ensemble et je vous proposerai un devis adapté à vos attentes et votre budget.
Contacter Clément Bernard