The API Documentation Generator: Turn Undocumented Endpoint Code Into Publish-Ready Docs
Why this prompt matters
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.
What we use it for
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)Result
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.
A two-pass prompt that reads your endpoint code, extracts the actual contract, and writes reference documentation that flags ambiguity instead of guessing — built for the gap between “the code works” and “the docs are live.”
Use Case
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.
Why It Matters
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.