claudekit/website/src/content/docs/commands/api-gen.md

title, description

title	description
/api-gen	Generate API endpoints, documentation, or client code from specifications

/api-gen

Purpose

Generate API endpoints, documentation, or client code from specifications. Accelerates API development by creating boilerplate code, OpenAPI specs, and client SDKs.

Usage

/api-gen [resource-name-or-spec]

Arguments

• resource-name-or-spec:
  • Resource name: User, Order, Product - Generate CRUD API
  • OpenAPI spec path: openapi.yaml - Generate from specification
  • Description: "User management API" - Generate from description

Workflow

Step 1: Define Resource

1. Identify resource properties

   • Field names and types
   • Required vs optional
   • Validation rules

2. Define relationships

   • One-to-many
   • Many-to-many
   • Foreign keys

3. Determine operations

   • CRUD operations needed
   • Custom endpoints
   • Business logic

Step 2: Generate Code

1. Create model/schema

   • Database model
   • Validation schema
   • Type definitions

2. Create routes/endpoints

   • HTTP methods
   • Path parameters
   • Request/response handling

3. Add validation

   • Input validation
   • Type checking
   • Error handling

4. Generate tests

   • Endpoint tests
   • Validation tests
   • Error case tests

Step 3: Document

1. Create OpenAPI spec

   • Endpoint descriptions
   • Request/response schemas
   • Authentication

2. Add examples

   • Request examples
   • Response examples
   • cURL commands

3. Document errors

   • Error codes
   • Error messages
   • Resolution steps

Examples

Generate CRUD API for Resource

/api-gen User

Creates:

• src/models/user.ts - Data model
• src/routes/user.ts - API routes
• src/controllers/user.ts - Business logic
• tests/user.test.ts - Test suite
• docs/api/user.md - API documentation

Generate from OpenAPI Spec

/api-gen openapi.yaml

Generates code matching the specification.

Generate with Description

/api-gen "Product catalog API with categories and tags"

Creates API based on natural language description.

Output

## API Generated: User Management

### Endpoints Created

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/users | List all users |
| POST | /api/users | Create new user |
| GET | /api/users/:id | Get user by ID |
| PUT | /api/users/:id | Update user |
| DELETE | /api/users/:id | Delete user |
| GET | /api/users/:id/posts | Get user's posts |

### Files Created

#### Model
- `src/models/user.ts`
  ```typescript
  export interface User {
    id: string;
    email: string;
    name: string;
    createdAt: Date;
    updatedAt: Date;
  }

  export const UserSchema = z.object({
    email: z.string().email(),
    name: z.string().min(1).max(100),
  });

Routes

• src/routes/user.ts

  router.get('/users', listUsers);
  router.post('/users', validateBody(UserSchema), createUser);
  router.get('/users/:id', getUser);
  router.put('/users/:id', validateBody(UserSchema), updateUser);
  router.delete('/users/:id', deleteUser);
  

Controller

• src/controllers/user.ts

  export async function createUser(req, res) {
    const user = await db.user.create({
      data: req.body,
    });
    res.status(201).json(user);
  }
  // ... other handlers
  

Tests

• tests/user.test.ts

  describe('User API', () => {
    it('should create user', async () => {
      const res = await request(app)
        .post('/api/users')
        .send({ email: 'test@example.com', name: 'Test' });
      expect(res.status).toBe(201);
      expect(res.body).toHaveProperty('id');
    });
  });
  

Documentation

• docs/api/user.md - Full API documentation

OpenAPI Specification

Generated openapi.yaml:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /api/users:
    get:
      summary: List all users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: Created

Next Steps

1. ✅ API endpoints generated
2. 🔧 Add authentication middleware
3. 🔧 Implement business validation
4. 🔧 Add pagination to list endpoint
5. 📝 Review and customize as needed

## Generation Modes

### CRUD Generation
```bash
/api-gen Product

Full Create, Read, Update, Delete operations

Spec-Based Generation

/api-gen swagger.json

Generate from existing OpenAPI/Swagger spec

Client Generation

/api-gen --client openapi.yaml

Generate TypeScript/Python client SDK

Documentation Only

/api-gen --docs-only api/

Generate documentation for existing endpoints

Flags

Flag	Description
--framework=[express|fastapi|nestjs]	Target framework
--db=[postgres|mongodb|prisma]	Database/ORM
--auth	Include authentication
--client	Generate client SDK
--docs-only	Documentation only
--test-framework=[jest|vitest|pytest]	Testing framework

Advanced Examples

Express + PostgreSQL + Auth

/api-gen Order \
  --framework=express \
  --db=postgres \
  --auth

FastAPI + MongoDB

/api-gen Product \
  --framework=fastapi \
  --db=mongodb

Generate Client SDK

/api-gen --client openapi.yaml

Creates TypeScript client:

import { UserAPI } from './generated/client';

const api = new UserAPI({ baseUrl: 'http://localhost:3000' });
const users = await api.getUsers();
const user = await api.createUser({
  email: 'test@example.com',
  name: 'Test User'
});

Resource Definition

When generating from resource name, you'll be asked:

### Define Resource: User

**Fields:**
1. email (string, required, unique)
2. name (string, required)
3. role (enum: user|admin, optional, default: user)
4. createdAt (datetime, auto)

**Relationships:**
- Has many: Post
- Belongs to: Organization (optional)

**Custom Endpoints:**
- POST /users/:id/verify-email
- POST /users/:id/reset-password

**Validation:**
- Email must be valid format
- Name: 1-100 characters
- Password: min 8 characters

Proceed with generation? (y/n)

OpenAPI Templates

Complete Endpoint

/api/orders:
  post:
    summary: Create new order
    tags:
      - Orders
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateOrder'
          examples:
            basic:
              value:
                items:
                  - productId: "123"
                    quantity: 2
                shippingAddress:
                  street: "123 Main St"
                  city: "New York"
    responses:
      '201':
        description: Order created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      '400':
        description: Invalid input
      '401':
        description: Unauthorized

Best Practices

1. Start with Design: Define API before generating
2. Review Generated Code: Don't blindly accept all generated code
3. Customize: Generated code is a starting point
4. Add Business Logic: Implement domain-specific validation
5. Security: Add authentication and authorization
6. Testing: Extend generated tests with edge cases

Use Cases

Rapid Prototyping

# Quickly scaffold multiple resources
/api-gen User
/api-gen Post
/api-gen Comment

API-First Development

# Design spec, then generate
# 1. Create openapi.yaml
# 2. Generate code
/api-gen openapi.yaml

Client SDK Distribution

# Generate client for API consumers
/api-gen --client openapi.yaml

Documentation Generation

# Document existing API
/api-gen --docs-only src/api/

Related Commands

• /doc - Generate documentation
• /feature - Full feature development
• /test - Generate tests
• /review - Review generated code