gh-hubexab-eaf-pluginclaude-plugins-test-plugin/commands/generate-api-client.md

# Generate API Client Command

Generate the TypeScript OpenAPI client library from the NestJS backend API specifications, ensuring type-safe communication between frontend and backend applications.

## Usage

```
/generate-api-client [--watch] [--validate]
```

## Parameters

- **--watch** (optional): Watch mode - regenerate client on backend API changes
- **--validate** (optional): Validate OpenAPI spec before generation

## What This Command Does

This command automates the process of generating a type-safe API client for the frontend to consume the backend API. It:

1. Extracts OpenAPI specification from the NestJS backend
2. Validates the specification for correctness
3. Generates TypeScript client code with full type definitions
4. Updates the `@bdqt/api-client` shared library
5. Ensures type safety across the monorepo

## Workflow

When you execute this command, Claude will:

1. **Backend API Specification Extraction**
   - Start the NestJS backend in development mode
   - Access the Swagger/OpenAPI endpoint (typically `/api-docs`)
   - Download the OpenAPI specification JSON
   - Validate the specification structure

2. **Specification Validation** (if --validate is used)
   - Check OpenAPI spec version (3.0 or 3.1)
   - Validate all endpoint definitions
   - Ensure all DTOs have proper typing
   - Verify authentication schemes are defined
   - Check for breaking changes from previous version

3. **Client Generation**
   - Use OpenAPI Generator or similar tool
   - Generate TypeScript client code with:
     - API service classes
     - Request/response type definitions
     - Model interfaces
     - Authentication helpers
     - HTTP client configuration

4. **Library Update**
   - Update `libs/api-client/src/` with generated code
   - Run TypeScript compilation
   - Generate TypeScript declarations
   - Update package exports

5. **Verification**
   - Compile the generated client
   - Run type checking
   - Verify all dependencies are satisfied
   - Run basic smoke tests

## Examples

### Basic Generation
```
/generate-api-client
```
Generates the API client from the current backend specification.

### Generate with Validation
```
/generate-api-client --validate
```
Validates the OpenAPI spec before generating the client.

### Watch Mode for Development
```
/generate-api-client --watch
```
Continuously regenerates the client when backend API changes are detected.

## Generated Client Structure

The command generates code in the `libs/api-client/` workspace:

```
libs/api-client/
├── src/
│   ├── api/
│   │   ├── users.api.ts           # Users API endpoints
│   │   ├── auth.api.ts            # Authentication endpoints
│   │   └── index.ts               # API exports
│   ├── models/
│   │   ├── user.model.ts          # User model interface
│   │   ├── auth.model.ts          # Auth-related models
│   │   └── index.ts               # Model exports
│   ├── client.ts                  # HTTP client configuration
│   ├── configuration.ts           # API configuration
│   └── index.ts                   # Main exports
├── package.json
└── tsconfig.json
```

## Client Usage Example

After generation, the frontend can use the type-safe client:

```typescript
// Frontend service example
import { UsersApi, CreateUserDto, User } from '@bdqt/api-client';

@Injectable()
export class UserService {
  private usersApi: UsersApi;

  constructor(private http: HttpClient) {
    this.usersApi = new UsersApi(http);
  }

  async createUser(data: CreateUserDto): Promise<User> {
    // Full type safety - TypeScript knows all properties
    return this.usersApi.createUser(data).toPromise();
  }
}
```

## Backend Decorators for OpenAPI

Ensure your NestJS controllers use proper decorators:

```typescript
@Controller('users')
@ApiTags('users')
export class UsersController {
  @Post()
  @ApiOperation({ summary: 'Create a new user' })
  @ApiResponse({ status: 201, description: 'User created', type: User })
  @ApiResponse({ status: 400, description: 'Invalid input' })
  async create(@Body() createUserDto: CreateUserDto): Promise<User> {
    return this.usersService.create(createUserDto);
  }
}
```

## Configuration

### Backend OpenAPI Setup

Ensure your NestJS backend has Swagger configured (typically in `main.ts`):

```typescript
// apps/backend/src/main.ts
const config = new DocumentBuilder()
  .setTitle('ExFabrica AF API')
  .setDescription('ExFabrica Agentic Factory API')
  .setVersion('1.0')
  .addBearerAuth()
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api-docs', app, document);
```

### Client Generator Configuration

Located in `libs/api-client/openapitools.json`:

```json
{
  "generator-cli": {
    "version": "6.2.0",
    "generators": {
      "typescript-angular": {
        "inputSpec": "../../apps/backend/openapi.json",
        "output": "./src",
        "generatorName": "typescript-axios",
        "additionalProperties": {
          "npmName": "@bdqt/api-client",
          "supportsES6": true,
          "withInterfaces": true,
          "useSingleRequestParameter": true
        }
      }
    }
  }
}
```

## Output Examples

### Success Output
```
🔧 Generating API Client
========================

✓ Backend API started on http://localhost:3000
✓ OpenAPI specification downloaded
✓ Specification validated (OpenAPI 3.0.3)
✓ Found 24 endpoints across 5 controllers
✓ Client code generated successfully
✓ TypeScript compilation successful
✓ Generated 24 API methods, 18 models

Summary:
--------
Endpoints: 24
Models: 18
Generated Files: 42
Size: 187 KB
Duration: 8.3s

The API client has been updated successfully! ✓

Updated workspace: @bdqt/api-client
```

### Validation Warnings
```
⚠️  Validation Warnings
-----------------------

1. Missing response type for DELETE /api/users/:id
   Location: UsersController.remove()
   Recommendation: Add @ApiResponse decorator

2. DTO missing property descriptions
   Location: CreateUserDto
   Affected: email, password, firstName, lastName
   Recommendation: Add @ApiProperty({ description: '...' })

3. Deprecated endpoint still in use
   Location: GET /api/auth/legacy-login
   Recommendation: Remove or mark with @Deprecated

Client generated successfully, but consider fixing these warnings.
```

## Watch Mode

When running with `--watch`, the command monitors:

- Changes to `*.controller.ts` files in backend
- Changes to `*.dto.ts` files in backend
- Changes to OpenAPI decorators
- Manual OpenAPI spec updates

On detecting changes:
1. Debounces for 2 seconds (batch multiple changes)
2. Re-extracts OpenAPI specification
3. Compares with previous version
4. Regenerates only if changes detected
5. Notifies you of the update

## Troubleshooting

### Backend Not Starting
```
Error: Cannot start backend server
```
**Solution**: Ensure backend dependencies are installed and database is running
```bash
yarn install
docker compose up -d
```

### OpenAPI Spec Invalid
```
Error: Invalid OpenAPI specification
```
**Solution**: Check backend controller decorators and DTOs
- Ensure all endpoints have proper @ApiOperation
- Verify DTOs have @ApiProperty decorators
- Check for circular references

### Type Generation Errors
```
Error: Failed to generate TypeScript types
```
**Solution**: Update OpenAPI generator version
```bash
cd libs/api-client
yarn add -D @openapitools/openapi-generator-cli@latest
```

### Circular Dependency Detected
```
Error: Circular reference in User -> Profile -> User
```
**Solution**: Restructure models or use lazy imports
```typescript
// Use string reference instead of direct import
@ApiProperty({ type: () => 'Profile' })
profile?: Profile;
```

### Missing Authentication Types
```
Error: Cannot find 'Authorization' header type
```
**Solution**: Add authentication configuration to OpenAPI setup
```typescript
.addBearerAuth({ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' })
```

## Breaking Changes Detection

The command detects breaking changes between versions:

**Breaking Changes**
- Removed endpoints
- Changed request/response types
- Removed model properties
- Changed authentication requirements

**Non-Breaking Changes**
- New endpoints
- New optional properties
- Added documentation
- New response codes

If breaking changes are detected, you'll receive a warning and recommendations for migration.

## Best Practices

1. **Regenerate after backend API changes**
   ```
   # After modifying backend controllers/DTOs
   /generate-api-client --validate
   ```

2. **Use watch mode during active development**
   ```
   /generate-api-client --watch
   ```

3. **Commit generated client with backend changes**
   - Keeps frontend and backend in sync
   - Enables type checking across the monorepo

4. **Document your API properly**
   ```typescript
   @ApiOperation({
     summary: 'Create user',
     description: 'Creates a new user account with the provided details'
   })
   @ApiResponse({
     status: 201,
     description: 'User successfully created',
     type: User
   })
   ```

5. **Version your API**
   - Use API versioning in routes (`/api/v1/users`)
   - Generate separate clients for different versions if needed

## Integration with Development Workflow

### Before Deployment
```bash
/generate-api-client --validate
/test-all
/deploy staging
```

### After Backend Changes
```bash
# Make backend changes
/generate-api-client
# Update frontend to use new types
/test-all frontend
```

### In CI/CD Pipeline
```yaml
- task: Script@1
  displayName: 'Generate API Client'
  inputs:
    script: |
      /generate-api-client --validate

- task: Script@1
  displayName: 'Verify No Changes'
  inputs:
    script: |
      git diff --exit-code libs/api-client/
      # Fails if generated code differs (means it wasn't regenerated)
```

## Advanced Usage

### Custom Generator Configuration

Modify `libs/api-client/openapitools.json` for custom generation:

```json
{
  "additionalProperties": {
    "npmName": "@bdqt/api-client",
    "supportsES6": true,
    "withInterfaces": true,
    "useSingleRequestParameter": true,
    "modelPropertyNaming": "camelCase",
    "enumPropertyNaming": "UPPERCASE"
  }
}
```

### Multiple API Versions

Generate clients for different API versions:

```bash
/generate-api-client v1
/generate-api-client v2
```

Each version gets its own namespace:
- `@bdqt/api-client/v1`
- `@bdqt/api-client/v2`

## Related Commands

- `/test-all` - Test generated client integration
- `/deploy` - Deploy after client generation
- `/analyze-code` - Verify generated code quality

## Benefits

✓ **Type Safety**: Full TypeScript typing across frontend-backend boundary
✓ **Auto-completion**: IDE support for all API methods and models
✓ **Error Prevention**: Catch API mismatches at compile time
✓ **Documentation**: Generated client includes JSDoc from backend
✓ **Consistency**: Single source of truth for API contracts
✓ **Productivity**: No manual API client maintenance

---

**Note**: Always regenerate the client after making changes to backend API endpoints, DTOs, or authentication schemes to maintain type safety across the monorepo.