Écrire la partie que le générateur ne peut pas
La doc générée répond à « que prend cet endpoint ». Personne n’a jamais été bloqué par cette question.
API Documentation génère à partir de vos collections, puis ajoute un éditeur de texte enrichi, la gestion de versions, la génération d’extraits de code, l’export PDF et des liens partageables.
La moitié générée est complète et juste, et n’aide personne à elle seule. Ce qui bloque un développeur n’est jamais la liste des paramètres.
Ordonnez le document pour un lecteur qui découvre
Les listes d’endpoints sont généralement alphabétiques, l’ordre qui ne sert personne. Mettez le document dans l’ordre où l’on intègre :
- Comment s’authentifier, avec un exemple complet qui fonctionne.
- L’appel unique qui prouve que la configuration marche — la plus petite requête qui renvoie quelque chose.
- Le flux principal, dans l’ordre où il se déroule.
- Tout le reste, par ordre alphabétique, car à ce stade le lecteur cherche plus qu’il ne lit.
Un lecteur qui atteint un premier appel réussi devient patient. Un lecteur qui n’arrive pas à s’authentifier en dix minutes écrit au support et reste agacé.
Documentez les erreurs, pas le succès
Toute doc générée décrit le 200. Presque aucune ne décrit le 409 signifiant que l’e-mail est déjà enregistré, ni ce que le client doit en faire : réessayer, afficher un message, ou basculer sur un autre appel.
Écrivez le tableau des erreurs à la main. C’est la section la plus lue et la seule qui raccourcit les échanges avec le support.
Quand figer une version
La gestion de versions gagne sa place le jour où quelqu’un d’extérieur à votre équipe construit sur l’API. Figez une version à ce moment-là, pas à un jalon de release.
La raison est pratique : quand vous modifierez un champ, la personne qui a intégré au trimestre précédent a besoin du document tel qu’il était, pas d’une entrée de changelog expliquant qu’il a bougé. Partager un lien vers une version précise ne coûte rien et clôt le débat avant qu’il n’ait lieu.
Pour tout ce qui a des lecteurs externes, partagez un lien plutôt qu’un PDF. Le lien suit la version ; un PDF devient faux dès le lendemain de son envoi.
Questions fréquentes
Dans quel ordre présenter la documentation ?
L’authentification avec un exemple complet, puis le plus petit appel qui prouve que ça marche, puis le flux principal dans l’ordre, puis le reste par ordre alphabétique. L’alphabétique dès le début ne sert personne qui intègre pour la première fois.
Que dois-je écrire à la main ?
Les erreurs et la raison d’être de chaque endpoint. Le générateur couvre entièrement les paramètres ; personne n’a jamais été bloqué par une liste de paramètres, et tout le monde l’a été par un 409 inexpliqué.
Quand figer une nouvelle version ?
Le jour où quelqu’un hors de votre équipe commence à construire sur l’API, pas à un jalon de release. Cette personne aura besoin du document tel qu’il était lors de son intégration, pas d’une note disant qu’un champ a bougé.
