Ce prompt transforme du code d’endpoint en documentation API prête à publier
Why this prompt matters
Undocumented endpoints slow down every team that touches them. Engineers waste time reading handlers, support teams answer the same integration questions repeatedly, and partner launches slip because nobody is fully sure which fields are required or what errors to expect. A prompt like this turns documentation from an afterthought into a release artifact.
What we use it for
Use this prompt when you are shipping or reviewing an API endpoint and the docs are lagging behind the code. It is especially useful when a backend engineer needs to turn a route handler, schema, and a few response examples into publishable docs before a release, SDK handoff, or partner integration.
Prompt
Role: Act as a senior API technical writer and backend engineer who documents production endpoints for developer platforms. Context: I will give you one or more API endpoint handlers, route definitions, validation schemas, example responses, and optional business context. The code may be incomplete, spread across files, or mixed with framework boilerplate. Task: Produce accurate, developer-facing API documentation that another engineer can use without reading the original code first. Constraints: - Use only behavior supported by the code or by clearly labeled assumptions. - Do not invent parameters, status codes, auth rules, rate limits, or side effects that are not shown. - If the code is ambiguous, create an "Open questions" section instead of guessing. - Keep naming consistent with the source code. - Prefer concrete examples over abstract explanations. - Call out risky gaps such as missing validation, undocumented error paths, or unclear auth behavior. Output Format: 1. Endpoint Summary - Method: [HTTP METHOD] - Path: [ENDPOINT PATH] - Purpose: one paragraph 2. Authentication and Permissions 3. Request Details - Path parameters - Query parameters - Headers - Request body schema - Validation rules 4. Response Details - Success response with JSON example - Error responses with likely causes 5. Business Logic Notes - Important side effects - Derived fields or hidden rules 6. Edge Cases and Limitations 7. Open Questions 8. Ready-to-publish docs block in clean Markdown Input to use: - Framework/language: [FRAMEWORK OR LANGUAGE] - Route definition(s): [PASTE ROUTE CODE] - Handler/service code: [PASTE HANDLER OR SERVICE CODE] - Validation schema: [PASTE SCHEMA OR "none"] - Example request/response: [PASTE EXAMPLES OR "none"] - Business context: [OPTIONAL CONTEXT OR "none"]
Result
Endpoint Summary - Method: POST - Path: /v1/projects/{projectId}/invites - Purpose: Creates a pending workspace invite for a new team member and optionally sends an email invitation. This endpoint is intended for project admins who need to grant access without manually provisioning users in the dashboard. The code shows that the invite is tied to a specific project, stores the target email in normalized lowercase form, and rejects duplicate active invites for the same address.
Authentication and Permissions The route is protected by `requireSession()` and then checks `assertProjectRole(projectId, user.id, ['owner', 'admin'])`. That means authenticated users can call the endpoint, but only project owners and admins can successfully create invites. There is no evidence of token-based API authentication in the provided code, so this should be documented as session-authenticated unless another auth layer exists outside the snippet.
Request Details **Path parameters** - `projectId` (string, required): Unique project identifier used to scope the invite and permission check.
**Headers** - `Content-Type: application/json` - Auth session cookie or equivalent session header, required by `requireSession()`
**Request body schema** ```json { "email": "[email protected]", "role": "editor", "sendEmail": true } ```
**Validation rules** - `email` must be present, trimmed, lowercased, and pass email validation - `role` must be one of `viewer`, `editor`, or `admin` - `sendEmail` is optional and defaults to `true`
Response Details **Success, 201 Created** ```json { "inviteId": "inv_8f2c1", "projectId": "prj_123", "email": "[email protected]", "role": "editor", "status": "pending", "expiresAt": "2026-05-02T10:30:00.000Z" } ```
**Error responses** - `400 Bad Request`: invalid email, invalid role, or malformed JSON body - `403 Forbidden`: caller is authenticated but lacks admin or owner role - `409 Conflict`: an active invite for the same email already exists in this project
Business Logic Notes - Invite expiration is derived from `now + 7 days`, not supplied by the caller - Duplicate checking happens before insert, but the snippet does not show a unique DB constraint, so concurrent requests may still race unless enforced elsewhere - If `sendEmail` is true, the endpoint queues `mail.enqueueProjectInvite()` after the database write
Edge Cases and Limitations - The code does not show rate limiting, so bulk invite abuse protection is unclear - Error handling around email queue failure is ambiguous. If queuing fails after insert, the invite may exist without an email being sent - There is no visible audit-log write, which may matter for enterprise customers
Open Questions - Is there a database uniqueness constraint on `(projectId, email, status=pending)`? - What happens if `mail.enqueueProjectInvite()` fails after the invite row is created? - Are service tokens allowed to use this endpoint, or only browser sessions?
Ready-to-publish docs block in clean Markdown ### Create a project invite Creates a pending invite for a new project member. Only project owners and admins can call this endpoint. The server validates the email, checks the requested role, prevents duplicate active invites, and returns the new pending invite object.
**POST** `/v1/projects/{projectId}/invites`
**Requires authentication:** Yes **Required role:** `owner` or `admin`
#### Request body - `email` string, required - `role` enum (`viewer`, `editor`, `admin`), required - `sendEmail` boolean, optional, default `true`
#### Success response Returns `201 Created` with the pending invite object, including `inviteId`, `projectId`, `email`, `role`, `status`, and `expiresAt`.
#### Common errors - `400` invalid input - `403` insufficient permissions - `409` duplicate pending invite
La documentation API se dégrade souvent de manière prévisible. L’endpoint est livré, le code change une ou deux fois, et la documentation prend du retard ou n’arrive jamais. Le résultat est connu : les ingénieurs lisent directement les handlers, les partenaires posent les mêmes questions dans Slack, et le support devient la source de vérité officieuse.
Ce Prompt est conçu pour combler cet écart. Il prend les définitions de routes, le code des handlers, les schémas de validation et quelques exemples de payload, puis les transforme en documentation structurée qu’un autre développeur peut réellement utiliser. L’intérêt ne se limite pas au résumé. Le Prompt oblige le modèle à distinguer ce que le code prouve de ce qui relève de l’hypothèse, à lister les erreurs probables et à produire des questions ouvertes lorsque le comportement reste ambigu.
La structure compte beaucoup. La partie Role place le modèle à la fois comme technical writer et backend engineer, ce qui améliore la précision. Les Constraints font un vrai travail : elles empêchent d’inventer des règles d’auth, des paramètres ou des status codes. En rédaction API, une phrase fausse mais formulée avec assurance est pire qu’un manque clairement identifié.
L’Output Format rend aussi ce Prompt très pratique. Au lieu d’une explication vague, il fournit les détails de l’endpoint, la documentation request/response, les notes de business logic, les edge cases et un bloc Markdown prêt à publier. Un développeur peut ainsi passer du code à une première version de la documentation en une seule étape, puis réserver la relecture humaine aux zones réellement floues.
Si votre équipe publie des API internes, des API partenaires ou des produits destinés aux développeurs, c’est le genre de Prompt qu’il faut conserver. Il réduit la friction de livraison et rend la documentation plus fiable parce qu’elle part du code qui tourne réellement.