Logo Ocean blanc

Général • Brief

Développement d’un support de documentation API à destination des équipes techniques. 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 aux personnes ne disposant pas de compétences en développement.

Destiné à fournir des informations pratiques et des explications sur les services, ce support est épaulé par Swagger, outil de description d’API déjà en place mais limité.

Mockup site documentation API webservice

Décrire 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.

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 un but de documentation. Les fonctions de description d’API ont été apportées par un thème développé à cet escient.

Pages • Chapitre

Structure
  simple

En me 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

Screenshot description objet retour

Description de l’objet retour

Pages • Simple

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èle de page en front-end

Symfony

Pour gérer l’architecture globale relative à Grav et certaines fonctionnalités

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

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