API Documentation Generator | Claude Skill

When to use

Triggers:

"Document this API" / "Generate API docs"
"Write OpenAPI / Swagger spec"
"API reference for [service or endpoint]"
"Postman collection for [endpoints]"
"How should I document our API?"
Pasting code/routes and asking for documentation

Don't fire for:

Consumer app user guides (different audience — not developers)
Internal runbooks for ops teams (use process-documentation-writer)
Frontend component library docs (use Storybook or a framework-specific tool)

The 4 documentation modes

1. Doc-first

Write the OpenAPI spec before writing the code. The spec becomes the contract.

Best for:

Teams with multiple services
Public-facing APIs with partner consumers
When you want server + client generated from the same spec

Tooling: OpenAPI 3.1, Stoplight Studio, Swagger Editor, VS Code with OpenAPI plugin

2. Code-first

Annotate your existing code routes. Doc is generated at build time.

Best for:

Internal APIs where docs follow implementation
Rapid early-stage iteration
Teams where writing a spec first feels heavy

Tooling:

Node/TypeScript: tsoa, zod-to-openapi, hono-openapi
Python: FastAPI (native), Flask-Smorest, Django REST Framework's drf-spectacular
Ruby: Rswag, apipie-rails
Go: swaggo/swag
Java/Kotlin: Springdoc-openapi

3. Hybrid

Maintain a hand-written OpenAPI spec + generate from code where it's easier. Merge at build.

Best for:

Mature products where different subsystems have different maintainers
When some endpoints are generated, others are hand-crafted for DX quality

4. Retroactive

Your API exists but isn't documented. You're writing docs from scratch.

Best for: Reality — most AU SME API-first businesses land here eventually.

Approach:

Audit the endpoints from routes/code
Categorise by domain (auth, users, billing, admin, etc.)
Document the high-traffic / external-facing endpoints first
Work your way down

The minimum viable API documentation

For every endpoint, document:

1. The one-liner

"POST /users — Create a new user"

One sentence. No jargon. First line someone reads.

2. Authentication

What auth scheme? (Bearer token? API key in header? OAuth?)
Where does the token come from?
What happens if auth fails? (401 / 403 / specific error)

3. Request

Path parameters — name, type, example, description
Query parameters — name, type, required/optional, default, example, description
Headers — which ones matter (Content-Type, Authorization, custom like X-API-Version)
Body schema — full JSON schema with types, required fields, examples

4. Response

Status codes — 200/201/204 for success, what each means
Response schema — full structure with types
Example response — actual JSON, not abstract field names

5. Errors

Status codes — 400 / 401 / 403 / 404 / 409 / 422 / 429 / 500 — which does this endpoint return?
Error response schema — consistent across the API (error code, message, details)
Common causes — for each error code, what typically triggers it

6. Rate limits

Limit — requests per minute/hour
Identifier — per-user, per-IP, per-API-key
Response when limited — usually 429 with Retry-After header
How to check your current usage

7. Examples

cURL — always
Language SDK examples (if you have SDKs) — at minimum JavaScript + Python + (for Australia-relevant) PHP + Ruby
Postman collection — a downloadable JSON

8. Related endpoints

Which endpoints typically come before or after this one in a workflow
Link to the related endpoints

Full endpoint template

## POST /api/users

Create a new user in your workspace.

### Authentication

Bearer token in `Authorization` header. Token must have `users:write` scope.

### Request

**Path parameters**: None

**Query parameters**: None

**Body** (`application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| email | string | yes | Valid email address |
| name | string | yes | Display name, 1–64 chars |
| role | string | no | `admin` / `member` / `viewer`. Default: `member` |
| metadata | object | no | Arbitrary key-value pairs |

Example:

```json
{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "member"
}

Response

201 Created:

{
  "id": "usr_abc123",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "member",
  "created_at": "2026-04-22T10:30:00Z",
  "metadata": {}
}

Errors

| Status | Error code | When | |---|---|---| | 400 | invalid_email | Email format invalid | | 400 | name_too_long | Name exceeds 64 chars | | 409 | email_exists | User with that email already exists | | 403 | insufficient_scope | Token lacks users:write scope | | 429 | rate_limited | Exceeded 100 writes/min for your workspace |

Error response format:

{
  "error": {
    "code": "email_exists",
    "message": "A user with this email already exists",
    "details": {
      "existing_user_id": "usr_xyz789"
    }
  }
}

Rate limit

100 requests per minute per workspace. 429 response with Retry-After: 45 header when exceeded.

Examples

cURL:

curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "name": "Jane Smith"}'

JavaScript (fetch):

const res = await fetch("https://api.example.com/api/users", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "jane@example.com",
    name: "Jane Smith"
  })
});
const user = await res.json();

Python (requests):

import requests

r = requests.post(
    "https://api.example.com/api/users",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={"email": "jane@example.com", "name": "Jane Smith"}
)
user = r.json()

Related endpoints

GET /api/users/:id — fetch a user
PATCH /api/users/:id — update a user
DELETE /api/users/:id — delete a user
POST /api/invites — invite (sends an email) instead of directly creating


## Cross-cutting sections every API doc needs

### Authentication overview (one page)

- All auth schemes supported
- How to get a token
- Token lifetime + refresh
- Scopes + permissions
- How to revoke

### Error handling (one page)

- Consistent error response format across the API
- HTTP status code conventions
- How to handle rate limiting
- When to retry vs when not to

### Versioning (one page)

- Current version + supported older versions
- How breaking changes are signalled
- Deprecation policy + timeline

### Webhooks (if applicable)

- How to register
- Event types + schemas
- Signing + verification
- Retry behaviour

### SDKs (if applicable)

- Which languages supported
- Installation per language
- Quick-start code for each

### Changelog

- API changes by date
- What changed (fields added/removed, behaviour changes, new endpoints)

### Rate limits + quotas (one page)

- All limits in one place
- How to check current usage
- How to request higher limits

## Tools worth using

### OpenAPI spec editors

- **Stoplight Studio** — visual + spec-first; free tier good
- **Swagger Editor** — open-source, simple
- **VS Code OpenAPI plugin** — if your team lives in VS Code

### Rendered documentation

- **Redoc** — free, clean, read-only; good for reference docs
- **Swagger UI** — interactive "try it" playground; busier visual
- **Stoplight Elements** — hybrid; nicer than Swagger UI
- **Scalar** — modern, fast-loading, good DX; growing adoption
- **Mintlify** — commercial, very polished; consider if docs are a product

### Collection / testing tools

- **Postman** — near-universal; export collections from your OpenAPI spec
- **Insomnia** — lighter alternative; good DX
- **Bruno** — open-source alternative with Git-friendly collections

### Diff + linting

- **Spectral** — lint OpenAPI specs for consistency
- **openapi-diff** — catch breaking changes in CI

## For AU SME / early-stage API-first businesses

If you're just starting and want 80% of the value for 20% of the effort:

1. Write an OpenAPI 3.1 spec (doc-first or retrofit from code)
2. Host it on Scalar or Redoc (free)
3. Generate a Postman collection from the spec
4. Host the spec at `/api/openapi.json` so people can import
5. Add a `/docs` page to your site that renders the spec
6. Changelog in GitHub Releases or a simple Markdown file

That's it. You don't need Mintlify or a dedicated docs platform for under 50 endpoints.

## AU-specific considerations

- **Data residency in docs** — if data is AU-hosted, say so; if it's US/EU, say so. Matters for Privacy Act compliance conversations your customers will have.
- **Currency in examples** — use AUD where relevant, not defaulting to USD
- **Date formats** — ISO 8601 with explicit TZ (not DD/MM/YYYY in API responses — leave that to frontends)
- **Time zones** — state the API's TZ; most mature APIs use UTC

## Output format

Per request:

1. **OpenAPI 3.1 spec** (YAML or JSON) — if the user wants the spec file itself
2. **Per-endpoint documentation** — markdown, per the template above
3. **Cross-cutting pages** — auth, errors, versioning (if the user has multiple endpoints)
4. **Example SDK calls** — in 2–3 common languages
5. **Postman collection** — JSON format

## What this skill does NOT do

- **Build the API itself.** Documentation follows implementation (or design-first, it precedes it) — but the skill documents, it doesn't code the endpoints.
- **Set up hosted docs.** You deploy Redoc / Scalar / Mintlify yourself.
- **Auto-update docs when code changes.** That's a CI-pipeline step you set up.
- **Advise on REST vs GraphQL vs gRPC** — architectural choice; docs come later.

## Tier access

**Base.** Niche but important for API-first products. Pro-tier adds auto-generation from a codebase + docs-linting pre-commit hook setup.

## Related skills

- `process-documentation-writer` — for runbooks and internal ops docs
- `code-review-assistant` — docs and code review are adjacent; new endpoints should ship with new docs
- `seo-audit` — docs pages rank for long-tail keyword searches; relevant for API discovery

## References

- [OpenAPI Specification 3.1](https://spec.openapis.org/oas/v3.1.0)
- [Stoplight — OpenAPI guide](https://stoplight.io/openapi)
- [Stripe API docs — the gold standard](https://docs.stripe.com/api)
- [Redoc](https://github.com/Redocly/redoc), [Scalar](https://scalar.com/), [Swagger UI](https://swagger.io/tools/swagger-ui/)