API Client Generator Skill

# API Client Generator Skill

---
slug: api-client-generator-skill
version: 1.0.0
category: engineering
command: /gen-client
---

## What it does
Generates a typed API client from a set of endpoint descriptions or an OpenAPI/Swagger
document. Produces: request and response type definitions, one method per endpoint,
error handling with typed error classes, and a usage example. Defaults to TypeScript;
adapts to Python (httpx + dataclasses) or Go (net/http + structs) when stated.

## Trigger
Use this skill when asked to generate, write, or scaffold an API client.
Typical invocations:
- "Generate a TypeScript client for this REST API"
- "Write a typed client from this OpenAPI spec"
- `/gen-client` in Claude Code
- `/gen-client <spec>` where spec is a URL, pasted JSON/YAML, or an endpoint list

## Input
Provide one or more of:
1. An OpenAPI/Swagger document (JSON or YAML, pasted or file path)
2. A list of endpoints with method, path, request body shape, and response shape
3. The target language (TypeScript/Node, Python, Go — defaults to TypeScript)
4. The HTTP library to use (fetch, axios, httpx, net/http — defaults to fetch for TypeScript)
5. Auth scheme (Bearer token, API key header, OAuth — include if known)

If no spec is provided, ask for endpoint descriptions before proceeding.

## Method

1. **Extract types** — derive TypeScript interfaces (or Python dataclasses, Go structs) for every
   request body and response schema. Name types after the resource and operation.
2. **Generate methods** — one function per endpoint; accept typed parameters, build the URL, set headers.
3. **Handle errors** — create a typed error class that wraps HTTP errors and includes status code,
   endpoint, and the raw response body. Do not swallow errors silently.
4. **Auth** — inject the auth header in a single place (not repeated in each method).
5. **Usage example** — show three representative calls with real-looking (not placeholder) data.

### Rules
- Do not use `any` in TypeScript output. Use `unknown` and narrow explicitly.
- Keep the client thin: no caching, no retry logic, no global state unless asked.
- Group related endpoints into a namespace object or class (e.g., `client.users.get()`).
- If the spec has pagination, generate a typed paginated response type; do not hide it.

## Output format

Produce one file (or two for large specs: `types.ts` and `client.ts`), then a short **Usage** section.

## Example output

**Spec**: Two endpoints — GET /users/:id and POST /users

```typescript
// types.ts
export interface User {
  id: string;
  name: string;
  email: string;
  createdAt: string;
}

export interface CreateUserRequest {
  name: string;
  email: string;
}

export interface ApiErrorBody {
  message: string;
  code: string;
}
```

```typescript
// client.ts
import type { User, CreateUserRequest, ApiErrorBody } from './types';

export class ApiError extends Error {
  constructor(
    public readonly status: number,
    public readonly endpoint: string,
    public readonly body: ApiErrorBody,
  ) {
    super(`${status} ${endpoint}: ${body.message}`);
    this.name = 'ApiError';
  }
}

async function apiFetch<T>(endpoint: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${process.env.API_BASE_URL}${endpoint}`, {
    ...init,
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.API_TOKEN}`,
      ...init?.headers,
    },
  });
  if (!res.ok) {
    const body: ApiErrorBody = await res.json();
    throw new ApiError(res.status, endpoint, body);
  }
  return res.json() as Promise<T>;
}

export const client = {
  users: {
    get: (id: string) => apiFetch<User>(`/users/${id}`),
    create: (body: CreateUserRequest) =>
      apiFetch<User>('/users', { method: 'POST', body: JSON.stringify(body) }),
  },
};
```

**Usage**
```typescript
const user = await client.users.get('usr_01J9XZ');
const newUser = await client.users.create({ name: 'Ada Lovelace', email: 'ada@example.com' });
```

## Commands (Claude Code)

- `/gen-client` — Generate a typed API client from the pasted endpoint descriptions or OpenAPI spec.
- `/gen-client <spec>` — Generate a client from a specific spec file path, URL, or pasted document.