---
name: api-docs-writer
description: Documents HTTP endpoints from the real code - method, path, auth, parameters, request and response examples, error codes - so examples match the actual handlers. Use when a service has undocumented or outdated API docs, or the user asks to document an API.
---

# API Docs Writer

API docs that disagree with the code are worse than none. Read the handlers, document what they actually do, and prove each example against the running service or the tests.

## Workflow

1. Find every route. Search the router definitions and decorators for the framework in use, for example:
   ```
   grep -rnE "(app|router)\.(get|post|put|patch|delete)\(" src
   grep -rnE "@(app|router)\.(get|post|put|patch|delete)" .
   ```
   Also check route files by convention (file-based routers like `app/api/**/route.ts`), middleware mounted on path prefixes, and any OpenAPI or schema file already in the repo. Treat an existing OpenAPI file as a hint, not a source of truth.
2. For each route, read the handler and what it calls. Extract:
   - method and full path (including prefixes added where routers are mounted)
   - auth: none, session cookie, bearer token, API key; which middleware enforces it; required roles or scopes
   - path, query, header and body parameters with type, required or optional, default, limits and validation rules (read the validator or schema)
   - the success response: status code and body shape
   - every error the handler can return: status, body shape and the condition that causes it
   - side effects, pagination, rate limits, idempotency
3. Produce examples from reality. Prefer the repo's tests and fixtures. Otherwise run the service locally with dummy config and call it with `curl`, then copy the real output. If you cannot run it, derive examples from the code and mark them "not executed".
4. Write the docs in the format already used by the project. If none exists, use one Markdown file with one section per resource.
5. Cross-check: pick three endpoints at random and re-verify path, required params and one error code against the code.

## Per-endpoint format

````
### POST /v1/orders

Create an order. Auth: bearer token (`orders:write`).

Body (JSON)
| Field | Type | Required | Notes |
|---|---|---|---|
| item_id | string | yes | must exist |
| quantity | integer | no | 1-100, default 1 |

Example
```
curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "itm_123", "quantity": 2}'
```

201 response
```
{ "id": "ord_456", "status": "pending" }
```

Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error": "quantity_out_of_range"} | quantity outside 1-100 |
| 401 | {"error": "unauthorized"} | missing or invalid token |
| 404 | {"error": "item_not_found"} | unknown item_id |
````

## Rules

- Use environment placeholders such as `$TOKEN` and `example.com` in examples. Never include real keys, tokens, customer data or internal hostnames, and never print secrets while testing.
- Document the error shape once globally if consistent, then list codes per endpoint.
- Document what the code enforces, including the surprising: ignored unknown fields, silent clamping, case-sensitive values, trailing-slash behavior.
- Call out undocumented but reachable routes (debug, admin, health) and ask the user whether to publish or omit them.
- Keep field names exactly as in the code, including casing.
- When the code is ambiguous or inconsistent (two handlers return different error shapes), report it as a finding instead of choosing silently.

## Pitfalls

- Documenting from route names without reading the handler.
- Forgetting prefixes added by a router mount or a reverse proxy.
- Examples that fail validation because required fields were left out.
- Running mutating requests against a real or shared environment. Use a local or disposable instance and ask first.
- Describing planned behavior (TODO branches) as available.

## Report back

Files written, number of endpoints documented, which examples were executed versus derived, and discrepancies or suspicious behavior found in the code.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
