Este prompt transforma código de endpoint em documentação de API pronta para publicar
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
A documentação de API costuma quebrar de um jeito previsível. O endpoint vai para produção, o código muda duas vezes e a documentação fica para trás ou nunca aparece. O resultado também é conhecido: engenheiros leem os handlers diretamente, parceiros repetem as mesmas dúvidas no Slack e o suporte vira a fonte informal da verdade.
Este Prompt foi feito para fechar essa lacuna. Ele recebe definições de rota, código de handler, validation schema e exemplos de payload, e transforma isso em documentação estruturada que outro desenvolvedor consegue usar sem abrir o código primeiro. O valor não está só no resumo. O Prompt força o modelo a separar comportamento comprovado pelo código de suposições, listar erros prováveis e abrir perguntas quando o comportamento não estiver claro.
A estrutura importa. O Role posiciona o modelo como technical writer e backend engineer ao mesmo tempo, o que aumenta a precisão. As Constraints fazem o trabalho pesado: impedem regras de auth inventadas, parâmetros adivinhados e status codes fictícios. Em documentação técnica, uma frase confiante e errada é pior do que uma lacuna visível.
O Output Format também torna este Prompt realmente útil. Em vez de produzir uma explicação vaga, ele entrega detalhes do endpoint, documentação de request e response, notas de business logic, edge cases e um bloco de Markdown pronto para publicar. Isso permite sair do código para um primeiro rascunho de documentação em uma única passada, deixando a revisão humana focada nas partes realmente ambíguas.
Se sua equipe publica APIs internas, APIs para parceiros ou produtos voltados a desenvolvedores, este é o tipo de Prompt que vale guardar. Ele reduz o atrito no release e torna a documentação mais confiável porque parte do código que realmente está em execução.