Prompticon
prompt ChatGPT

Prompt ChatGPT pour documenter une API : générez une doc claire et complète

Ce prompt ChatGPT génère une documentation API structurée avec endpoints, paramètres, exemples de requêtes et codes d'erreur. Prête à publier.

chatgptcodingapidocumentationdeveloper-toolsprompt

Documenter une API est l’une de ces tâches que tout développeur repousse. Le code évolue, la doc stagne, et les collègues finissent par lire directement le code source pour comprendre comment appeler un endpoint. Le résultat : des intégrations cassées, des questions répétitives sur Slack et du temps perdu. Ce prompt transforme ChatGPT en rédacteur technique qui produit une documentation API structurée, avec exemples de requêtes, codes d’erreur et notes d’implémentation.

Le prompt

You are a senior technical writer specializing in API documentation. Generate comprehensive, developer-friendly documentation for the following API.

**API Name**: [API_NAME]
**Base URL**: [BASE_URL]
**Authentication**: [AUTH_METHOD — e.g., "Bearer token in Authorization header", "API key in X-API-Key header", "OAuth 2.0"]

**Endpoints to document**:
[PASTE_YOUR_ENDPOINTS — route, method, brief description. Example:
- POST /users — Create a new user
- GET /users/:id — Get user by ID
- PUT /users/:id — Update user
- DELETE /users/:id — Delete user]

**Request/Response examples** (if available):
[PASTE_ANY_EXISTING_EXAMPLES_OR_SCHEMAS]

For each endpoint, produce:
1. **Method + Path** — clearly formatted
2. **Description** — one sentence explaining what this endpoint does
3. **Authentication** — required or not, which scopes/permissions
4. **Path parameters** — name, type, description
5. **Query parameters** — name, type, required/optional, default value, description
6. **Request body** — JSON schema with field descriptions and validation rules
7. **Response** — success response with example JSON, status code
8. **Error responses** — table of possible error codes with descriptions
9. **Code example** — a working cURL request and a code snippet in [LANGUAGE — e.g., JavaScript fetch, Python requests]

Format the output in Markdown. Use tables for parameters and error codes. Make examples realistic — no "foo" or "bar".

Comment utiliser ce prompt

  1. Copiez le prompt ci-dessus
  2. Remplacez les variables :
    • [API_NAME] : le nom de votre API (ex. “User Management API”)
    • [BASE_URL] : l’URL de base (ex. “https://api.example.com/v1”)
    • [AUTH_METHOD] : la méthode d’authentification utilisée
    • [PASTE_YOUR_ENDPOINTS] : la liste de vos endpoints avec méthode HTTP et description courte
    • [PASTE_ANY_EXISTING_EXAMPLES_OR_SCHEMAS] : schémas ou exemples existants (optionnel)
    • [LANGUAGE] : le langage pour les exemples de code
  3. Collez dans ChatGPT (GPT-4o recommandé pour la précision)
  4. Relisez et ajustez : vérifiez les types de données et les codes d’erreur contre votre implémentation réelle

Exemple de résultat

Entrée

API Name: Task Management API
Base URL: https://api.taskflow.io/v1
Authentication: Bearer token in Authorization header

Endpoints to document:
- POST /tasks — Create a new task
- GET /tasks/:id — Get task by ID
- PATCH /tasks/:id — Update task fields

Language for code examples: JavaScript fetch

Sortie

POST /tasks

Crée une nouvelle tâche dans le projet spécifié.

Authentification : requise (Bearer token)

Request body :

ChampTypeRequisDescription
titlestringouiTitre de la tâche (3-200 caractères)
projectIdstring (UUID)ouiID du projet parent
assigneeIdstring (UUID)nonID de l’utilisateur assigné
prioritystringnonlow, medium, high, urgent. Défaut : medium
dueDatestring (ISO 8601)nonDate d’échéance

Réponse (201 Created) :

{
  "id": "d4e5f6a7-b8c9-4d0e-a1b2-c3d4e5f6a7b8",
  "title": "Migrer la base de données vers PostgreSQL 16",
  "projectId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "assigneeId": null,
  "priority": "medium",
  "status": "todo",
  "dueDate": null,
  "createdAt": "2026-04-07T10:30:00Z"
}

Erreurs :

CodeDescription
400Champs requis manquants ou validation échouée
401Token manquant ou expiré
404projectId introuvable
422priority invalide ou dueDate dans le passé

Exemple cURL :

curl -X POST https://api.taskflow.io/v1/tasks \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Migrer la base de données vers PostgreSQL 16", "projectId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "priority": "high"}'

Exemple JavaScript :

const response = await fetch("https://api.taskflow.io/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer eyJhbGci...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Migrer la base de données vers PostgreSQL 16",
    projectId: "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    priority: "high",
  }),
});
const task = await response.json();

Pourquoi ce prompt fonctionne

Le rôle de technical writer oriente ChatGPT vers un format professionnel. Sans cette assignation, le modèle produit souvent une doc trop verbeuse ou trop vague — ni l’un ni l’autre n’est utile à un développeur qui veut intégrer l’API rapidement.

La structure imposée par endpoint (paramètres, body, réponse, erreurs, exemple) garantit l’exhaustivité. Chaque endpoint suit le même format, ce qui rend la doc prévisible et facile à parcourir. Les développeurs qui intègrent une API ne lisent pas — ils scannent.

Les exemples réalistes font la différence entre une doc qu’on utilise et une doc qu’on ignore. En demandant explicitement “no foo or bar”, le prompt force des données crédibles qui permettent de comprendre immédiatement le format attendu.

Variantes

Pour documenter une API existante à partir du code source

You are a senior technical writer. Read the following API route handlers and generate complete API documentation in Markdown.

**Framework**: [FRAMEWORK — e.g., Express, FastAPI, Spring Boot]
**Code**:
[PASTE_ROUTE_HANDLER_CODE]

For each route found in the code, document: method, path, parameters, request body, response format, error cases, and a cURL example. Infer validation rules from the code logic.

Pour générer une doc au format OpenAPI/Swagger

You are an API architect. Convert the following endpoint descriptions into a valid OpenAPI 3.1 YAML specification.

**API Name**: [API_NAME]
**Base URL**: [BASE_URL]
**Endpoints**:
[ENDPOINT_LIST]

Include: schemas with $ref, example values for every field, error responses (400, 401, 404, 500), and security scheme definition. Output valid YAML only.

Conseils pour de meilleurs résultats

  • Fournissez vos schémas existants. Si vous avez des types TypeScript, des modèles Prisma ou des schémas JSON, incluez-les. ChatGPT produira des types bien plus précis qu’en devinant à partir des noms d’endpoints.
  • Documentez par groupe de 3-5 endpoints. Un prompt avec 20 endpoints produit une doc bâclée à la fin. Découpez par ressource (users, orders, products) et exécutez le prompt plusieurs fois.
  • Vérifiez les codes d’erreur. ChatGPT invente des codes d’erreur plausibles mais pas toujours corrects. Croisez chaque tableau d’erreurs avec votre middleware d’erreurs réel.

Prompts associés