Gerador de Documentação de API a partir do Código do 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] ```
O que este Prompt Faz
Escrever documentação de API é uma das tarefas mais demoradas no desenvolvimento de software — e uma das mais ignoradas. Este prompt transforma código bruto de endpoint em documentação completa e pronta para o desenvolvedor: descrição do endpoint, método HTTP, parâmetros de caminho, parâmetros de consulta, esquema do corpo da requisição, esquema de resposta, códigos de status, tratamento de erros e exemplos em curl. Tudo em uma única passada.
O Prompt
O prompt completo está acima. Aqui está o que cada seção faz e por que é importante:
Por que a Instrução de Papel Funciona
Dizer à IA para atuar como um redator técnico sênior de API com expertise em REST e OpenAPI 3.0 não é apenas um enfeite — isso ativa um modo de saída específico. O modelo produz documentação estruturada com vocabulário adequado em vez de parágrafos genéricos sobre o que o código faz.
Por que Você Deve Incluir o Bloco de Código Completo
Código parcial ou apenas a assinatura da função gera documentação incompleta. O prompt instrui você a colar o manipulador completo do endpoint — incluindo middleware, lógica de validação e tratamento de erros — porque é lá que a documentação real está. O modelo lê as regras de validação e as converte diretamente em restrições de parâmetros como required: true, minLength: 3, type: string.
A Seção de Formato de Saída
Sem instruções explícitas de formato de saída, os modelos escrevem documentação em prosa. Este prompt especifica uma divisão estruturada: Visão Geral do Endpoint, Especificação da Requisição, Especificação da Resposta, Tabela de Códigos de Erro e um exemplo em curl. Este é o formato que vai direto para um README, documento Notion ou arquivo Swagger sem reformatação.
Como é o Exemplo de Saída
Para um endpoint POST /api/users/register, você obtém:
- Visão geral do endpoint: Método, caminho, requisito de autenticação, observação sobre rate limiting
- Corpo da requisição: Esquema JSON com nomes de campos, tipos, restrições e se cada um é obrigatório
- Resposta: Esquema de sucesso 201, além das formas de erro 400/409/422/500
- Tabela de erros: Código de status, string do código de erro, significado e dica de correção
- Exemplo em curl: Um comando funcional com valores de amostra realistas
Melhor Usado Com
Este prompt funciona melhor com Claude 3.7 Sonnet ou GPT-4o. Ambos lidam de forma confiável com tarefas de código para documentação. Para endpoints com lógica de validação complexa (Joi, Zod, Pydantic), o Claude tende a ser mais preciso ao extrair regras de restrição.
Adaptando para sua Stack
Os campos [FRAMEWORK] e [LANGUAGE] são importantes. "Express.js / Node.js" produz exemplos curl nativos em JavaScript. "FastAPI / Python" produz anotações de tipo no estilo Python e reconhece modelos Pydantic. Sempre preencha esses campos — eles alteram significativamente a qualidade da saída.