Documentation d’API REST

Les API REST sont l’avenir

Traiter de l’information par HTTP est le principe du Web. Chaque fois que vous « googlez » quelque-chose ou que vous utilisez une application mobile, vous cherchez à accéder à distance à des ressources via HTTP. Le but des API REST est d’accéder à des ressources qui sont dans le cloud en fournissant les chemins pour y accéder.

La force des API REST est qu’elles sont « language agnostic » : elles n’ont pas de préférence de langage car elles utilisent soit le format JSON soit XML. Elles sont donc universelles.

Il y a 20 ans, j’étais en charge de la documentation d’un message broker multi-plateformes dont le SDK était disponible en C++, Java et C. C’était un moyen de permettre à des plateformes ayant différents langages de communiquer entre elles. On a fait du chemin depuis !

RESTful API et OpenAPI

De plus en plus populaires, les API REST tendent à se doter de standards : cette API est-elle RESTful ou non ? Est-ce qu’elle correspond entièrement au design pattern REST ou pas ? Si oui, c’est une API RESTful ; si non, c’est « seulement » une API REST.

Un peu d’humour sur le sujet : Crédit image @Octo

OpenAPI est une spécification pour décrire les API REST qui utilisent des objets JSON. La standardisation facilite le travail des outils de parsing qui génèrent un rendu après analyse du code, et il y a maintenant une grande variété d’outils de publication qui vont de l’outil par défaut Swagger Editor à toutes sortes de templates très attractifs.

Ce qui est plaisant dans les OpenAPI (du point de vue du rédacteur) c’est que l’API et sa documentation sont dans le même fichier. On écrit la documentation en ajoutant des lignes de description directement dans le fichier OpenAPI. On est au plus près du code et j’aime ça.

L’offre de service Coffee Cup pour la documentation d’API REST

La documentation peut être rédigée en français, en anglais ou en allemand.

Coffee Cup peut documenter votre API REST, qu’elle utilise JSON ou XML. J’adore ce type de travail !

Votre documentation sera-t-elle “DOCful” ?

|DOCful| est un jeu de mots de mon invention en relation avec RESTful 😃. Cependant, il n’est pas juste là pour divertir. Il a pour objectif aussi d’établir une sorte de standard sur la documentation des API REST.

Une documentation DOCful devrait être composée d’une documentation de référence et d’une documentation utilisateur.

1. La documentation faite dans les champs “description” du fichier OpenAPI est une documentation de référence. Les routes, méthodes, clés & valeurs et les codes retours sont documentés de manière systématique, de manière aussi exhaustive que possible.

2. On devrait toujours compléter la documentation par une documentation utilisateur. Celle-ci étant hors du fichier OpenAPI on peut rédiger le contenu dans des fichiers Markdown et utiliser un générateur de site statique pour l’assemblage et la publication, ce qui permet d’avoir un rendu très attractif et professionnel.

Cette documentation utilisateur inclut :

• Vue d’ensemble, schémas, information générale
• Guide de démarrage
• Tutoriels et procédures
• Liste des codes de statut et d’erreur
• Glossaire

Bien qu’on puisse insérer des paragraphes entiers et des images/schémas dans la partie introduction du fichier Swagger, ce n’est en fait pas le lieu. La documentation Utilisateur est l’endroit approprié pour “s’étaler” et fournir le maximum d’informations.

J’ai récemment testé Docusaurus V2, qui est un excellent générateur de sites statiques avec des fonctionnalités performantes et des options visuelles vraiment séduisantes. Ses challengers que sont Jekyll et VuePress sont de très bonnes alternatives.

Dans le cadre d’une documentation DOCful, j’ai particulièrement apprécié le plugin ReDoc développé pour Docusaurus V2 qui permet de centraliser l’accès à la fois à la documentation utilisateur et à l’OpenAPI.

Si vous préférez avoir une documentation séparée de l’API, c’est également possible. L’information sera « extraite » du code et structurée dans un fichier.

🔗 Consultez mon Portfolio. 🔗 D’autres infos dans mes Favoris

Outils

Swagger Editor, Git, Visual Studio Code et tout outil permettant de lire/modifier/publier du code. Un générateur de site statique pour avoir un beau rendu (par exemple, un template ReDoc).

Le présent site web utilise la syntaxe Markdown, le générateur de site statique Hugo et un sympathique template.