O Gerador de Documentação de API: Transforme Código de Endpoint Não Documentado em Documentação Pronta Para Publicação

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

{
  "refund_id": "rf_8h2j9k",
  "payment_id": "pay_4f5e6d",
  "amount_cents": 2500,
  "status": "succeeded",
  "created_at": "2026-08-10T09:12:00Z"
}

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"}'