Generador de documentación de API a partir del código del 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] ```
Qué hace este Prompt
Escribir documentación de API es una de las tareas que más tiempo consume en el desarrollo de software, y una de las que más se omiten. Este Prompt convierte código de endpoint en bruto en documentación completa y lista para el desarrollador: descripción del endpoint, método HTTP, parámetros de ruta, parámetros de consulta, esquema del cuerpo de la solicitud, esquema de respuesta, códigos de estado, manejo de errores y ejemplos curl. Todo en una sola pasada.
El Prompt
El Prompt completo está arriba. Aquí te explicamos qué hace cada sección y por qué es importante:
Por qué funciona la instrucción de rol
Indicarle a la IA que actúe como un escritor técnico senior de API con experiencia en REST y OpenAPI 3.0 no es solo un adorno: activa un modo de salida específico. El modelo genera documentación estructurada con vocabulario adecuado en lugar de párrafos genéricos sobre lo que hace el código.
Por qué debes incluir el bloque de código completo
El código parcial o solo la firma de la función produce documentación incompleta. El Prompt te indica que pegues el manejador del endpoint completo, incluyendo middleware, lógica de validación y manejo de errores, porque ahí es donde reside la documentación real. El modelo lee las reglas de validación y las convierte directamente en restricciones de parámetros como required: true, minLength: 3, type: string.
La sección de formato de salida
Sin instrucciones explícitas de formato de salida, los modelos escribirán documentación en prosa. Este Prompt especifica un desglose estructurado: Resumen del endpoint, Especificación de la solicitud, Especificación de la respuesta, tabla de códigos de error y un ejemplo curl. Este es el formato que se puede colocar directamente en un README, un documento de Notion o un archivo Swagger sin necesidad de reformatear.
Cómo se ve el ejemplo de salida
Para un endpoint POST /api/users/register, obtienes:
- Resumen del endpoint: Método, ruta, requisito de autenticación, nota de limitación de tasa
- Cuerpo de la solicitud: Esquema JSON con nombres de campos, tipos, restricciones y si cada uno es obligatorio
- Respuesta: Esquema de éxito 201, más formas de error 400/409/422/500
- Tabla de errores: Código de estado, cadena de código de error, significado y sugerencia de corrección
- Ejemplo curl: Un comando funcional con valores de muestra realistas
Mejor usado con
Este Prompt funciona mejor con Claude 3.7 Sonnet o GPT-4o. Ambos manejan tareas de código a documentación de manera confiable. Para endpoints con lógica de validación compleja (Joi, Zod, Pydantic), Claude tiende a ser más preciso al extraer reglas de restricción.
Adaptarlo a tu Stack
Los campos [FRAMEWORK] y [LANGUAGE] son importantes. "Express.js / Node.js" produce ejemplos curl nativos de JavaScript. "FastAPI / Python" produce anotaciones de tipo al estilo Python y reconoce modelos Pydantic. Complétalos siempre: cambian significativamente la calidad de la salida.