Générateur de documentation API à partir du code d'endpoint
Why this prompt matters
API documentation debt compounds fast — endpoints shipped undocumented stay undocumented for months or years because no one wants to reverse-engineer them later. The typical cost: integration errors, support tickets, and delays every time a new developer touches that endpoint. This prompt eliminates the friction by making documentation the fastest part of shipping an endpoint, not an afterthought. The structured Role + Output Format approach is critical because without it, models produce prose summaries instead of the schema tables and curl examples that developers actually need for integration.
What we use it for
You have just finished writing a new API endpoint and need to hand it off to a frontend developer, a third-party integrator, or your own team. The endpoint has validation logic scattered across middleware and the controller, and writing the documentation by hand would take 30-45 minutes. This prompt lets you paste the code and get publish-ready documentation in under 30 seconds.
Prompt
Act as a senior API technical writer with deep expertise in REST API design and OpenAPI 3.0 documentation standards. Context: I have an API endpoint written in [FRAMEWORK] / [LANGUAGE] that needs complete, developer-ready documentation. The endpoint is part of [YOUR PROJECT NAME / DOMAIN]. Task: Analyze the following endpoint code and produce complete API documentation covering every detail a developer needs to integrate this endpoint correctly. ``` [PASTE YOUR FULL ENDPOINT HANDLER CODE HERE — include route definition, middleware, validation logic, controller/handler function, and error handling] ``` Constraints: - Do not omit any parameters you can infer from the code — if validation logic implies a constraint (e.g., minLength, required, enum values), include it - Do not guess at business logic that is not in the code — if something is unclear, mark it as [TO CLARIFY] - Keep all parameter names and field names exactly as they appear in the code - Use technical documentation vocabulary, not conversational descriptions Output Format — produce exactly these sections: ## Endpoint Overview - Method and path - Authentication requirement (inferred from middleware) - Rate limiting notes (if any) - Short description (1-2 sentences) ## Request Specification ### Path Parameters (table: name | type | required | description | constraints) ### Query Parameters (table: name | type | required | default | description | constraints) ### Request Body (table: field | type | required | description | validation rules) ## Response Specification ### Success Response (2xx) (schema with field names, types, example values) ### Error Responses (table: status code | error code | meaning | when it occurs | how to fix) ## Example Request ```bash curl [working example with realistic sample values matching all validation rules] ``` ## Example Response ```json [realistic JSON response matching the success schema] ```
Ce que fait ce prompt
Rédiger une documentation API est l'une des tâches les plus chronophages du développement logiciel — et l'une des plus souvent négligées. Ce prompt transforme le code brut d'endpoint en une documentation complète, prête pour les développeurs : description de l'endpoint, méthode HTTP, paramètres de chemin, paramètres de requête, schéma du corps de la requête, schéma de réponse, codes de statut, gestion des erreurs et exemples curl. Le tout en un seul passage.
Le prompt
Le prompt complet se trouve ci-dessus. Voici ce que fait chaque section et pourquoi c'est important :
Pourquoi l'instruction de rôle fonctionne
Dire à l'IA d'agir en tant que rédacteur technique API senior expert en REST et OpenAPI 3.0 n'est pas qu'une simple formule — cela active un mode de sortie spécifique. Le modèle produit une documentation structurée avec un vocabulaire approprié plutôt que des paragraphes génériques sur ce que fait le code.
Pourquoi vous devez inclure le bloc de code complet
Un code partiel ou simplement la signature de la fonction produit une documentation incomplète. Le prompt vous demande de coller l'intégralité du gestionnaire d'endpoint — y compris le middleware, la logique de validation et la gestion des erreurs — car c'est là que se trouve la véritable documentation. Le modèle lit les règles de validation et les convertit directement en contraintes de paramètres comme required: true, minLength: 3, type: string.
La section sur le format de sortie
Sans instructions explicites sur le format de sortie, les modèles produisent une documentation en prose. Ce prompt spécifie une décomposition structurée : Aperçu de l'endpoint, Spécification de la requête, Spécification de la réponse, Tableau des codes d'erreur, et un exemple curl. C'est le format qui peut être directement intégré dans un README, un document Notion ou un fichier Swagger sans reformatage.
À quoi ressemble l'exemple de sortie
Pour un endpoint POST /api/users/register, vous obtenez :
- Aperçu de l'endpoint : méthode, chemin, exigence d'authentification, note sur la limitation de débit
- Corps de la requête : schéma JSON avec noms de champs, types, contraintes et indication si chaque champ est obligatoire
- Réponse : schéma de succès 201, plus les formes d'erreur 400/409/422/500
- Tableau d'erreurs : code de statut, chaîne de code d'erreur, signification et indication de correction
- Exemple curl : une commande fonctionnelle avec des valeurs d'exemple réalistes
Meilleur avec
Ce prompt fonctionne mieux avec Claude 3.7 Sonnet ou GPT-4o. Les deux gèrent de manière fiable les tâches de conversion de code en documentation. Pour les endpoints avec une logique de validation complexe (Joi, Zod, Pydantic), Claude tend à être plus précis pour extraire les règles de contrainte.
L'adapter à votre stack
Les champs [FRAMEWORK] et [LANGUAGE] sont importants. "Express.js / Node.js" produit des exemples curl natifs JavaScript. "FastAPI / Python" produit des annotations de type à la Python et reconnaît les modèles Pydantic. Remplissez toujours ces champs — ils changent considérablement la qualité de la sortie.