Votre doc d'API est-elle DOCful ?

Les API REST sont l’avenir

La gestion de l’information via HTTP est la base du Web. Chaque fois que vous effectuez une recherche en ligne ou utilisez une application mobile, vous accédez à des ressources distantes via HTTP.

Les API REST offrent des chemins structurés pour accéder aux ressources hébergées dans le Cloud. Leur force réside dans leur indépendance vis-à-vis des langages — en utilisant JSON ou XML comme formats de message, elles sont universellement compatibles.

À mes débuts, j’ai travaillé sur un broker de messages multi-plateformes avec des SDK en C++, Java et C — une manière de relier des plateformes dépendantes des langages. Depuis, nous avons fait beaucoup de chemin !

API RESTful et OpenAPI

Avec leur popularité croissante, les API REST tendent à suivre des standards : sont-elles RESTful ou non ? Correspondent-elles entièrement au design pattern ? Si oui, elles sont RESTful. Sinon, elles ne sont que REST.

OpenAPI est une spécification permettant de décrire des API REST en JSON. Elle simplifie l’analyse et permet l’utilisation d’une large gamme d’outils de publication — de Swagger Editor à des templates modernes et élégants.

Ce qui rend OpenAPI si efficace pour la documentation ? L’API et sa documentation vivent dans le même fichier. Il suffit d’ajouter des champs de description et voilà — vous documentez directement dans le code. C’est efficace, proche de la source, et étonnamment agréable.

Votre documentation sera-t-elle DOCful ?

DOCful est un jeu de mots que j’ai inventé en 2019, inspiré de RESTful. Mais ce n’est pas qu’un clin d’œil — c’est un appel à de meilleurs standards pour la documentation des API REST.

J’ai émis le concept DOCful pour élever la documentation d'API à un niveau élevé de satisfaction développeur. Il combine une documentation de référence systématique avec des guides utilisateur complets et faciles d’accès.

Un ensemble documentaire DOCful inclut :

1. Documentation de référence : intégrée dans le fichier OpenAPI, elle doit être systématique et exhaustive.

2. Documentation utilisateur : rédigée en dehors du fichier OpenAPI — souvent en Markdown — et publiée via un générateur de site statique. Cela permet une présentation soignée et professionnelle.

La doc de référence couvre	La doc utilisateur couvre
- Routes, méthodes, paramètres - Clés & valeurs - Codes de retour et gestion des erreurs	- Présentations d’architecture et schémas - Guides de démarrage - Tutoriels et parcours guidés - Listes de statuts & codes d’erreur - Glossaires et conseils de dépannage

Bien que les fichiers Swagger – la documentation de référence – puissent intégrer un texte d’introduction et des schémas, ce n'est pas l'idéal du contenu plus étendu et détaillé. C’est là que la documentation utilisateur prend tout son sens.

DOCful : une évolution naturelle du docs-as-code

Le concept DOCful s’aligne naturellement avec l’approche docs-as-code, car les deux défendent l’idée que la documentation mérite une place de premier plan dans le cycle de développement logiciel.

En adoptant des langages de balisage légers, le contrôle de version et l’automatisation, DOCful permet aux équipes de créer du contenu modulaire, réutilisable et maintenu en continu — tout cela dans les mêmes workflows que ceux utilisés pour le code.
Cette synergie favorise la collaboration entre rédacteurs et développeurs, garantit que la documentation évolue avec le produit, et soutient des pipelines de publication évolutifs.

L’accent mis par DOCful sur une rédaction structurée et basée sur des composants complète parfaitement l’esprit docs-as-code, en faisant une base idéale pour des écosystèmes de documentation modernes et adaptés aux développeurs.

Outils que je recommande

Pour créer une documentation DOCful, j’utilise :

• Swagger Editor pour rédiger les fichiers OpenAPI
• Git et Visual Studio Code pour le contrôle de version et l’édition
• Des générateurs de sites statiques comme Docusaurus, MKDocs ou Jekyll

Mon préféré est Docusaurus, dont le style et l’écosystème de plugins sont impressionnants. Le plugin ReDocusaurus pour Docusaurus permet d’unifier la documentation de référence et la documentation utilisateur dans un seul portail — un rêve DOCful.

Swagger UI

Swagger UI met l’accent sur l’interactivité pour tester les API, tandis que ReDoc privilégie une documentation claire et lisible pour explorer de grandes spécifications.

Redoc

• Redoc est un outil open source qui génère une documentation d'API élégante et responsive à partir de spécifications OpenAPI. Il est reconnu pour sa mise en page soignée, son support du mode sombre et sa facilité d’intégration dans des sites statiques.
• ReDocusaurus est un preset de plugin qui intègre Redoc dans les sites Docusaurus. Il permet d’afficher la documentation OpenAPI aux côtés de vos guides utilisateur en Markdown, le tout dans un portail développeur unifié. Il prend en charge le mode sombre, les thèmes personnalisés et le rendu côté serveur.
• Redocly est l’entreprise derrière Redoc. Elle propose une suite d’outils et services commerciaux — dont une CLI, des portails hébergés et des options de personnalisation avancées — pour les équipes qui gèrent des projets de documentation d'API à grande échelle.

Exemple

Voir dans mon portfolio un exemple de documentation RESTAPI et intégration ReDoc pour Lineberty. Ce n’est pas le seul que j’ai réalisé, mais les autres ne sont pas accessibles publiquement et ne peuvent donc pas figurer dans mon portfolio.

Documentation RESTAPI en 2025 : ce qu’elle prend en charge

La documentation de votre API REST ne se contente pas d’informer — elle évolue avec votre produit. Je crée une documentation qui respecte les standards et workflows actuels :

• Compatibilité OpenAPI 3.1 – Les API REST sont de plus en plus définies avec la spécification OpenAPI 3.1, qui prend en charge les webhooks, les vocabulaires JSON Schema et une validation renforcée. Je veille à ce que votre documentation reste conforme et compatible avec l’avenir — que vous utilisiez Swagger Editor, Redocly ou des outils personnalisés.

• Versionnement sémantique & intégration CI/CD – La documentation doit évoluer avec votre API. Je prends en charge des stratégies de versionnement sémantique (ex. 1.2.3 → 1.3.0) et j’intègre les mises à jour de documentation dans votre pipeline CI/CD, pour que la documentation soit publiée à chaque nouvelle version. Cela signifie moins de références obsolètes et une intégration plus rapide pour chaque mise à jour.

• Consoles API interactives – Des interfaces comme Swagger UI et Redocly permettent aux développeurs de tester les endpoints, visualiser les réponses et résoudre les problèmes — sans quitter le portail documentaire. J’intègre ces consoles proprement dans votre site statique (ex. Docusaurus), pour relier le code à l’expérience utilisateur.

---

©Auteur : Florence Venisse, STW – Version révisée du 25/07/2025. "DOCful", un concept personnel introduit en 2019.