Gerador de Documentação de API a partir do Código do Endpoint
Porque é que este prompt importa
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.
Para que o usamos
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.