Un prompt de documentation API résout la procrastination qui suit les endpoints terminés : le code est déjà en production, mais les appelants doivent lire le code source pour deviner les paramètres, et chaque intégration relance les mêmes questions sur les types, les champs obligatoires et les codes d'erreur. Copiez le prompt ci-dessous, collez le code ou la définition de l'endpoint, renseignez les lecteurs et le format de sortie, et l'IA rendra l'objectif, un tableau de paramètres, un exemple de requête, un exemple de réponse et les codes d'erreur dans l'ordre où les appelants les cherchent vraiment. Vérifiez les champs et la documentation peut partir.
Dans quelle situation ce prompt est utile
Il convient aux endpoints qui ont déjà du code et à qui il ne manque que la documentation : un endpoint backend avant transmission aux développeurs frontend ou à un partenaire externe, un ancien projet qui rattrape sa documentation, ou un nouvel arrivant qui cartographie les entrées et sorties d'un ensemble d'endpoints avant de prendre le relais. Il ne peut pas confirmer les règles métier à votre place. Une logique de validation, des exigences d'autorisation ou des limites que le code n'énonce pas doivent seulement être signalées comme questions ouvertes, jamais inventées. Si les champs changent encore chaque jour, générez d'abord le seul tableau de paramètres et ajoutez les exemples une fois les champs stabilisés, pour éviter une documentation périmée la semaine même de sa rédaction.
Le prompt, prêt à copier
Tu es rédacteur de documentation API. À partir du code ou de la définition d'endpoint que je colle, écris une documentation qu'un appelant peut utiliser directement pour son intégration.
Code ou définition de l'endpoint : {{code_endpoint}}
Lecteurs visés : {{lecteurs}}
Authentification : {{methode_auth}}
Notes sur l'adresse de base : {{adresse_base}}
Consignes de sortie :
1. Commence par deux phrases sur ce que fait cet endpoint et quand l'appeler. Ne reformule pas le code.
2. Donne ensuite un tableau de paramètres. Pour chaque paramètre, indique son nom, son emplacement (chemin, requête, en-tête ou corps), son type, s'il est obligatoire et sa signification. Marque toute signification absente du code comme à confirmer ; ne devine pas.
3. Donne un exemple de requête complet et un exemple de réponse réussie. Les noms de champs et les types doivent correspondre exactement au code, et les valeurs d'exemple doivent être des données fictives et masquées.
4. Ajoute une section séparée sur les codes d'erreur. Liste uniquement les erreurs que le code déclenche réellement, avec la condition de déclenchement et ce que l'appelant doit faire. N'ajoute aucun code d'erreur absent du code.
5. Termine par une liste de questions ouvertes : règles de validation, exigences d'autorisation et cas limites que le code laisse flous, point par point, pour que je les confirme avant qu'ils n'entrent dans le texte principal.Comment remplir les variables
- Code de l'endpoint : collez le gestionnaire, la définition de route et les types de requête et de réponse associés, pas seulement un nom de fonction. Plus le contexte est complet, moins le tableau contient de lignes « à confirmer ».
- Lecteurs visés : précisez s'il s'agit de développeurs frontend internes, d'un partenaire externe ou d'un développeur backend nouvellement arrivé. Le public change le niveau de détail des exemples et la nécessité d'expliquer les termes métier.
- Authentification : indiquez jeton, signature ou authentification au niveau de la passerelle. S'il n'y en a aucune, écrivez-le explicitement au lieu de laisser le champ vide et de laisser l'IA inventer une section d'authentification.
- Adresse de base : décrivez seulement les environnements, par exemple des environnements de test et de production séparés. Ne mettez jamais de vraies clés ou de vrais identifiants dans le prompt.
Trois points à vérifier dans le brouillon
Premièrement, comparez chaque champ au code. Une IA transforme parfois un paramètre facultatif en paramètre obligatoire ou ajoute à un exemple un champ que le code ne renvoie jamais ; comparez donc le tableau aux types, mot pour mot. Deuxièmement, surveillez les codes d'erreur complétés avec trop de générosité : tout code ou statut introuvable dans le code source va dans la liste des questions ouvertes, pas dans la section des erreurs. Troisièmement, masquez correctement les données d'exemple. Remplacez numéros de téléphone, e-mails et numéros de commande par des valeurs manifestement fictives, au lieu de laisser de vraies données d'intégration dans la documentation.
Quand tout un ensemble d'endpoints a besoin de documentation, générez-en un à la fois pour garder des conventions de champs cohérentes ; en coller dix d'un coup fait se mélanger les tableaux de paramètres. L'ordre fonctionne aussi en sens inverse pendant l'intégration : quand un appelant signale un paramètre incohérent, utilisez d'abord le Prompt de débogage : collez l'erreur et le code, obtenez la cause racine en un passage pour savoir si la faute vient de la documentation ou de l'appel, puis corrigez cette page.
