API Documentation Prompt for Claude: Docs From Code

Most API docs drift because they’re written once and never compared to the code again. This prompt makes Claude derive the docs from the source, quote where each fact comes from, and flag anything it can’t confirm, so regenerating them after a change is a five-minute job.

The prompt

You are a technical writer who documents HTTP APIs for external developers. Accuracy matters more than completeness: never document behavior you cannot see in the code.

<context>
API name and base URL: {{API_NAME_AND_BASE_URL}}
Framework / language: {{FRAMEWORK}}
Authentication scheme (if known): {{AUTH}}
Audience: {{AUDIENCE}}
</context>

<source>
{{SOURCE_CODE}}
</source>

<instructions>
1. Find every endpoint in the source: method, path, and the handler that serves it.
2. For each endpoint, extract from the code:
   - path and query parameters, request headers, request body fields (name, type, required/optional, constraints, defaults)
   - success responses (status code and body shape)
   - error responses: every status code the handler, validation layer or middleware can return, and when
   - auth requirements and permission checks
3. Cite the source for each non-obvious fact as file:line or the function name.
4. Write one realistic request example (curl) and one response example per endpoint, using values consistent with the validation rules.
5. Anything implied but not visible in the source (rate limits, pagination defaults set elsewhere, side effects in other services) goes under "Unverified", not into the docs.
</instructions>

<output_format>
# {{API_NAME}}

## Authentication
...

## Endpoints
### METHOD /path
One-sentence summary.

**Parameters**
| Name | In | Type | Required | Description |

**Request body**
| Field | Type | Required | Constraints | Description |

**Responses**
| Status | When | Body |

**Example**
(curl request, then JSON response)

## Unverified
Bullet list of things to confirm with the API owners.
</output_format>

How to use it

• claude.ai: paste the router file, the handlers, the validation schemas (Zod, Pydantic, Joi, class-validator) and the error middleware into {{SOURCE_CODE}}. Without the schemas, Claude can’t know which fields are required.
• Claude Code: skip the paste. Say “use the API docs prompt in docs/prompts/api-docs.md on src/routes/orders” and let Claude read the files. Turning it into a skill takes a few minutes with our Claude Code skills guide.
• API / CI: run it in headless mode on changed route files and post the diff of the generated docs to the pull request.

Variables

Variable	What to put there
{{API_NAME_AND_BASE_URL}}	e.g. “Orders API, https://api.example.com/v2”
{{FRAMEWORK}}	e.g. Express + Zod, FastAPI, Spring Boot
{{AUTH}}	Bearer token, API key header, session cookie
{{AUDIENCE}}	Internal team, partners, public developers
{{SOURCE_CODE}}	Router, handlers, schemas, error middleware

Example output (illustrative)

### POST /orders
Creates an order for the authenticated customer.

**Request body**
| Field    | Type    | Required | Constraints        | Description          |
| items    | array   | yes      | 1-50 entries       | Line items to order  |
| couponId | string  | no       | uuid               | Applied before tax   |

**Responses**
| Status | When                                  | Body          |
| 201    | Order created                         | Order object  |
| 400    | Body fails schema (orders.schema.ts:12) | Error object |
| 409    | Coupon already used (orders.ts:88)    | Error object  |

## Unverified
- Rate limit: middleware is imported from @acme/limits, not visible here.

Tips and variations

• OpenAPI output: replace the output format with “Return an OpenAPI document in YAML” and the spec version you use.
• Changelog mode: give Claude the old docs plus the new code and ask only for what changed, grouped as added, changed and removed.
• Docs that stay fresh: connect a docs source such as Context7 when you document a third-party SDK, so Claude checks current library behavior.
• Pair with tests: the unit test generator prompt can turn the “Responses” table into contract tests.
• More technique: Claude prompting best practices.