Best ChatGPT Prompt for API Documentation
Turn your route handlers into docs developers actually read.
The Prompt
You are a senior technical writer who has documented APIs at scale (think Stripe, Twilio quality). Generate documentation for this endpoint. Documentation style: [OpenAPI / Stripe-style narrative / README-style / Postman / team-custom] Language / framework: [Python+FastAPI / Node+Express / Go / Ruby+Rails / etc.] The endpoint code: ``` [PASTE THE HANDLER + ROUTE DEFINITION + ANY MIDDLEWARE THAT MATTERS] ``` The data model (if relevant): ``` [PASTE THE SCHEMA / DATACLASS / STRUCT] ``` Who's reading this doc: [internal devs / external developers / partner integrators] Auth model: [API key / OAuth / JWT / cookie / none] Requirements: - Document: HTTP method, path, auth required, request params/body, response shape, status codes - For EVERY error status (4xx, 5xx) the endpoint can return, explain when it fires and what the developer should do - Include at least one working example: curl request + sample response - If you can infer rate limits or idempotency behavior from the code, note them - If a piece of the behavior isn't clear from the code (silent fallbacks, edge cases), FLAG it instead of guessing—ask me to confirm
How to Use This Prompt
- Paste the route handler AND the schema/model it uses — without the schema the docs will be vague
- Specify the doc style — OpenAPI is structured, Stripe-style is narrative; the output is very different
- Tell the model who the reader is — internal developer docs and external partner docs have different tone
- Paste into ChatGPT or Claude
- Read the “FLAG” section carefully — those are the questions you need to answer before the docs ship
The model will sometimes hallucinate error codes the endpoint doesn't actually return. After generation, grep your handler for every raise / throw / return Response(status= and verify the doc lists exactly those.
Example Output
Task: Document a POST /users/:id/refund endpoint that triggers an async refund
Response:
POST /users/:id/refund
Refund a charge for a specific user.
Auth: API key (Bearer token)
Path params:
id (string, required) — the user's UUID
Request body (application/json):
{
"charge_id": "ch_xxx", // required
"amount": 1500, // optional, defaults to full charge; in cents
"reason": "duplicate" // optional: duplicate | fraudulent | requested_by_customer
}
Responses:
202 Accepted — refund queued; returns { "refund_id": "rf_xxx", "status": "pending" }
400 Bad Request — charge_id missing, or amount > charge total
402 Payment Required — original payment method no longer available
404 Not Found — user or charge not found, or charge doesn't belong to user
409 Conflict — charge already fully refunded
429 Too Many Requests — more than 30 refund requests per minute per API key
Example:
curl -X POST https://api.example.com/users/usr_123/refund \
-H "Authorization: Bearer sk_live_xxx" \
-d '{"charge_id": "ch_abc", "amount": 500, "reason": "duplicate"}'
Tips to Get Better Results
- Document errors developers can actually fix. “500 internal error” tells the integrator nothing. “500 if the upstream payment processor times out — retry with exponential backoff” tells them what to do.
- Include a working example. Not pseudocode — a real curl command they can copy and run. Tested examples are the highest-trust signal docs can give.
- Cover the unhappy path. Most API docs document the happy path well and the error responses poorly. The error path is where integrators get stuck and write support tickets.
- Verify after generation. The model will occasionally invent status codes. Grep your handler for actual return statements and reconcile.