El Generador de Documentación de API: Convierte Código de Endpoints Sin Documentar en Documentación Lista Para Publicar
Por qué importa este prompt
Undocumented internal APIs generate a predictable tax on engineering time: the same few questions get asked in Slack every time someone new tries to integrate — what's the auth header called, is this field required, what does a 422 actually mean here — and each thread costs the answering engineer real focus time they don't get back. Worse, when partner-facing endpoints ship without documented error responses, integration bugs get traced back to a misunderstood status code instead of a misread field, turning into support tickets that a five-minute doc-writing pass would have prevented entirely.
Para qué lo usamos
You just merged a pull request that adds a new POST /api/v1/refunds endpoint to your team's billing service. The endpoint works, tests pass, but nobody wrote documentation — and your team lead just asked you to get docs into the developer portal before external partners can start calling it next week. You have the code in front of you and forty-five minutes before your next meeting.
Prompt
Act as a senior API technical writer who has documented REST APIs for developer platforms used by thousands of external engineers.
Context — here is what I'm working with:
- I'm going to paste the source code for [NUMBER OF ENDPOINTS] API endpoint(s), written in [LANGUAGE/FRAMEWORK, E.G. EXPRESS.JS, FASTAPI, SPRING BOOT]. The code includes the route handler, any middleware, and validation logic.
- [OPTIONAL: PASTE AN EXISTING DOC PAGE OR STYLE GUIDE HERE FOR TONE/FORMAT CONSISTENCY]
Code to document:
[PASTE YOUR ENDPOINT CODE HERE]
Task: Do this in two passes.
Pass 1 — Extract the contract: Read the code and infer, strictly from what's actually there, the HTTP method and path, the authentication requirement, every path/query/body parameter with its type and whether it's required, the success response shape and status code, and every error condition the code actually handles with its status code and message.
Pass 2 — Write the documentation: Using only what you extracted in Pass 1, produce publish-ready API documentation.
Constraints:
- Do not invent, assume, or infer any parameter, behavior, rate limit, or error case that isn't evidenced in the code itself.
- If something is ambiguous or the code doesn't make a behavior clear (e.g., what happens if an optional field is malformed), flag it under a "Needs Clarification" section instead of guessing.
- No marketing language ("powerful", "seamless", "easy to use") — this is reference documentation, not a landing page.
- Use standard HTTP status code conventions unless the code deviates from them, in which case document the actual deviation.
- Every example must be a working, copy-pasteable example, not a placeholder like "..." where a real value should be.
Output format (Markdown):
1. Endpoint summary — one line: what this endpoint does
2. Authentication — what's required, referencing the actual auth mechanism in the code
3. Request — method + full path; path parameters table (name, type, required, description); query parameters table; request body schema (if applicable) with types and required/optional
4. Response — success: status code + example JSON response; errors: table of status code, error condition, example error response
5. Example request — a working curl command with realistic (not placeholder) values
6. Needs Clarification — bullet list of anything ambiguous in the source code (omit this section entirely if nothing is ambiguous)Resultado
Endpoint summary
Processes a full or partial refund for a completed payment.
Authentication
Requires a bearer token with the payments:write scope, passed in the Authorization header. Requests without this scope return a 403.
RequestPOST /api/v1/refunds
Request body:
payment_id(string, required) — the ID of the original payment to refundamount_cents(integer, optional) — amount to refund in cents; if omitted, the full remaining payment amount is refundedreason(string, optional) — one ofduplicate,fraudulent,requested_by_customer; defaults torequested_by_customerif omitted
Response
Success (200):
{
"refund_id": "rf_8h2j9k",
"payment_id": "pay_4f5e6d",
"amount_cents": 2500,
"status": "succeeded",
"created_at": "2026-08-10T09:12:00Z"
}Errors:
404—payment_iddoes not match an existing payment409— refund amount exceeds the remaining refundable balance on the payment422—amount_centsis present but not a positive integer
Example request
curl -X POST https://api.example.com/v1/refunds \
-H "Authorization: Bearer sk_live_51H..." \
-H "Content-Type: application/json" \
-d '{"payment_id": "pay_4f5e6d", "amount_cents": 2500, "reason": "requested_by_customer"}'Needs Clarification
- The code does not specify what happens if a refund is requested on a payment that has already been fully refunded — worth confirming with the endpoint's author before this ships to partners.
Un prompt de dos pasadas que lee el código de tu endpoint, extrae el contrato real, y escribe documentación de referencia que señala la ambigüedad en lugar de adivinar — construido para el vacío entre “el código funciona” y “la documentación está publicada”.
Caso de Uso
Acabas de fusionar un pull request que añade un nuevo endpoint POST /api/v1/refunds al servicio de facturación de tu equipo. El endpoint funciona, las pruebas pasan, pero nadie escribió documentación — y tu líder de equipo acaba de pedirte que subas la documentación al portal de desarrolladores antes de que los socios externos empiecen a llamarlo la próxima semana. Tienes el código delante y cuarenta y cinco minutos antes de tu próxima reunión.
Por Qué Importa
Las APIs internas sin documentar generan un impuesto predecible sobre el tiempo de ingeniería: las mismas pocas preguntas se hacen en Slack cada vez que alguien nuevo intenta integrarse —cómo se llama el header de autenticación, si este campo es obligatorio, qué significa realmente un 422 aquí— y cada hilo le cuesta al ingeniero que responde tiempo de concentración real que nunca recupera. Peor aún, cuando los endpoints de cara a socios se lanzan sin respuestas de error documentadas, los errores de integración se rastrean hasta un código de estado malentendido en lugar de un campo mal leído, convirtiéndose en tickets de soporte que un repaso de cinco minutos escribiendo documentación habría evitado por completo.