Par , le 4 mai 2015

Documenter son API REST avec API Blueprint

Développement | 0

Écrire de la documentation est contraignant. D’autant plus que cette dernière doit être régulièrement mise à jour à mesure que le projet évolue, ne faisant qu’accroître le côté fastidieux de la chose.

Documenter une API n’est pas plus aisé, toutes les requêtes et réponses différentes de chaque endpoint doivent être renseignées. De plus, une API n’est pas forcément à destination des développeurs, elle doit donc être facile à comprendre.

Il y a trés peu de gems pour documenter une API, mais heureusement plusieurs services existent. Les plus populaires sont RAML, Apiary et Swagger.
Ils utilisent tous les 3 des formats différents :

  • RAML : un language basé sur le YAML ;
  • Swagger : du JSON ou du YAML ;
  • Apiary : markdown (API Blueprint) ;

Mon choix s’est tourné vers Apiary, car je trouve que le markdown est plus lisible et maintenable que les 2 autres lorsque l’on travaille sur de gros projets.

Nous allons rapidement faire le tour des quelques outils open-source permettant de documenter une API :

  • API Blueprint pour écrire de la documentation ;
  • Dredd pour valider que celle-ci est cohérente ;
  • Aglio pour la transformer en HTML ;
  • Drakov pour créer un serveur HTTP de test.

API Blueprint

API Blueprint est un langage orienté documentation créée pour décrire une API sous forme de texte brut (markdown).
étant simple à apprendre et à lire, cela facilite la collaboration avec tous les membres de l’équipe aussi bien les développeurs front-end que le product owner. Ainsi tout le monde peut modifier la documentation.

Voici un exemple décrivant l’index d’une ressource :

api-1

Cet exemple simple, spécifie les paramètres de l’url, le code HTTP de retour, les en-tête, et donne un exemple de JSON retourné.

Les spécifications d’API Blueprint prouvent que le format est bien plus complet et permet, entre autres, de :

  • décrire plusieurs requêtes différentes pour le même endpoint ;
  • définir la structure du JSON avec le format MSON ou ajouter directement un schéma JSON.

Malheureusement, décrire plusieurs réponses selon les paramètres de l’url n’est pas encore disponible.
Vous pourrez voir sur le repo Github que le projet est trés actif et que cette fonctionnalité ne devrait pas tarder à arriver.

Dredd

Dredd est un outil qui va vérifier les écarts entre la documentation et la mise en œuvre réelle.
Il se penche sur les en-têtes, le code HTTP, le format de réponse et le corps exact de retour, et vous fait savoir s’il y a des différences dans l’un de ces éléments.
Il ne dépend pas d’un langage de programmation ou de framework car il intéragit avec l’application back-end à travers la couche HTTP mais peut démarrer lui-même un serveur qu’on lui aura paramétré dans un fichier de configuration ou utiliser directement une url.

$ dredd apiary.md http://localhost:3000

Le résultat de la commande ci-dessus :

dredd_output-1430722848049

Les logs du serveur :

dredd_console-1430722836046

On pourrait penser qu’il fait un bon outil pour les tests d’intégration, mais il ne permet pas d’insérer des fixtures avant chaque tests, et ne créer qu’un seul test par couple url/verbe HTTP.
Il faut garder en mémoire qu’il ne vérifie uniquement que la documentation est en adéquation avec l’API.

Aglio

Petit outil qui génère un fichier HTML basé sur un fichier API Blueprint.

aglio-1430722965071

Voici le rendu de notre blueprint avec le thème par défaut. A savoir qu’il est possible d’en utiliser d’autres fournies par Aglio ou d’en créer un nouveau.

Drakov

Lorsque les développeurs front-end travaillent sur l’interface, l’API n’est peut-être pas encore pleinement fonctionnelle, aussi pour ne pas ralentir le développement, il est utile d’avoir un faux serveur qui leur permettra de tester rapidement chaque endpoint. C’est ce que propose Drakov.

Conclusion

API Blueprint est un très bon format pour décrire une API, son apprentissage est rapide et ne rend pas difficile la maintenance de la documentation.
De très bon outils ont été construit autour de ce format et permettent d’améliorer les méthodes de travail.

Vous pouvez aussi utiliser directement le service d’Apiary qui regroupe tous ces outils dans un éditeur en ligne.

Partager l'article :

Vous souhaitez réagir ?

En soumettant ce commentaire vous donnez à Silicon Salad le droit de citer vos propos ainsi que votre nom/site. Tous commentaires dégradants ou hors-sujet peuvent-être supprimés par décision de l’auteur. Votre e-mail, ne sert qu’à des fins d’authentification, il ne peut-être ni partagé ni diffusé.
Vous pouvez commenter avec la syntaxe Markdown. En savoir plus

Article précédent
Penser à mon prochain