For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/building-apis/dto-generation.md.

DTO Generation

Generate type-safe TypeScript clients and NestJS DTOs from your OpenAPI specifications. This enables shared contracts between services with full validation and documentation support.

What Gets Generated

From a single OpenAPI spec, the generator produces two outputs:

OutputLocationPurpose
HTTP Client + Interfacespackages/{name}-client/src/Type-safe API calls for frontend and services
DTO Classespackages/{name}-client/dto/Runtime validation and Swagger docs for NestJS

Quick Start

Generate a Client

From your service directory:

npm run client:generate

Or using the CLI directly:

# Auto-detect service from current directory
npx tsdevstack generate-client

# Specify service name
npx tsdevstack generate-client auth-service

# Custom OpenAPI path
npx tsdevstack generate-client auth-service --input ./custom/path.json

The command auto-derives everything from the service:

  • Output → packages/{service-name}-client/
  • Package name → @shared/{service-name}-client
  • Author → from service's package.json

It then:

  1. Generates the HTTP client and TypeScript interfaces
  2. Generates DTO classes with validation decorators
  3. Builds the package automatically

Use the Generated Client

In a frontend application:

import { Api } from '@shared/auth-service-client';
import type { UserDto, PlanDto } from '@shared/auth-service-client';

// Create client with base URL
const client = new Api({ baseURL: process.env.NEXT_PUBLIC_API_URL });

// Public endpoints (no auth)
const plans = await client.v1.getPlans();

// Authenticated endpoints (pass JWT token)
const user: UserDto = await client.v1.getUserAccount({
  headers: { Authorization: `Bearer ${accessToken}` }
});

In a NestJS service (BFF or backend):

import { UserDto } from '@shared/auth-service-client/dto';

@Controller('v1/users')
export class UsersController {
  @Get()
  @ApiResponse({ status: 200, type: UserDto })
  async get(): Promise<UserDto> {
    return { /* ... */ };
  }
}

Writing DTOs That Generate Well

Follow these patterns in your source DTOs to ensure clean client generation.

Always Specify Explicit Types

Every @ApiProperty decorator must include an explicit type specification:

import { ApiProperty } from '@nestjs/swagger';

export class UserDto {
  @ApiProperty({
    description: 'User ID',
    example: 'usr_123',
    type: String,  // Required
  })
  id: string;

  @ApiProperty({
    description: 'User age',
    example: 25,
    type: Number,
  })
  age: number;

  @ApiProperty({
    description: 'Created at',
    example: '2024-01-15T10:30:00Z',
    type: Date,
  })
  createdAt: Date;
}

Use Lazy Resolvers for Nested Objects

Prevent circular dependencies by using arrow functions:

import { PlanDto } from './plan.dto';

export class UserPlanDto {
  @ApiProperty({
    description: 'Plan details',
    type: () => PlanDto,  // Arrow function prevents circular deps
  })
  plan: PlanDto;
}

Arrays

@ApiProperty({
  description: 'List of tags',
  type: [String],
  example: ['tag1', 'tag2'],
})
tags: string[];

@ApiProperty({
  description: 'List of plans',
  type: () => [PlanDto],  // Lazy resolver for object arrays
})
plans: PlanDto[];

Enums and Nullable Properties

@ApiProperty({
  description: 'System role of the user',
  enum: ['USER', 'ADMIN'],
  example: 'USER',
  type: String,
})
systemRole: 'USER' | 'ADMIN';

@ApiProperty({
  description: 'Optional notes',
  example: 'VIP customer',
  nullable: true,
  type: String,
})
notes: string | null;

Generated Output

The generated DTO classes include validation decorators automatically:

// Generated from your OpenAPI spec
export class UserDto {
  @IsDefined()
  @IsString()
  @ApiProperty({ required: true })
  id: string;

  @IsOptional()
  @IsString()
  @ApiProperty({ required: false, nullable: true })
  notes?: string | null;

  @IsDefined()
  @IsArray()
  @IsString({ each: true })
  @ApiProperty({ required: true })
  roles: string[];
}

The validators come from each property's OpenAPI type: strings, numbers and booleans get @IsString(), @IsNumber() or @IsBoolean(), and arrays get @IsArray() plus the item check with { each: true }. Nested objects, maps (Record<string, ...>), unions and file (binary) fields get no type validator.

Date Handling

Dates in source DTOs become strings in generated clients. This is correct because JSON serializes dates as ISO 8601 strings:

// Source DTO
@ApiProperty({ type: Date })
createdAt: Date;

// Generated client DTO
createdAt: string;  // Reflects actual HTTP contract

Common Issues and Solutions

Circular Dependency Errors

Error:

Error: A circular dependency has been detected (property key: "someProperty")

Solution: Add explicit type specifications to all @ApiProperty decorators, and use lazy resolvers for nested objects:

// Add type: String, type: Number, etc. to all properties
@ApiProperty({ type: String })
id: string;

// Use arrow functions for nested objects
@ApiProperty({ type: () => OtherDto })
other: OtherDto;

ConfigService Undefined During Generation

Error:

TypeError: Cannot read properties of undefined (reading 'get')

Solution: Use defensive coding in service constructors:

constructor(private config: ConfigService) {
  // Use optional chaining for doc generation compatibility
  this.value = this.config?.get<string>('KEY', 'default') ?? 'default';
}

Import Errors for Generated DTOs

Error:

Cannot find module '@shared/my-client/dto'

Checklist:

  1. Verify the package is built: ls packages/auth-service-client/dist/dto/
  2. Check package.json has the /dto export configured
  3. Run npm install in your consuming project

Generated DTOs Are Interfaces Instead of Classes

This indicates a template configuration issue. The generator should produce classes with decorators. Contact the platform team if you encounter this.

Package Structure

After generation, your client package will have this structure:

packages/auth-service-client/
  src/
    Api.ts          # HTTP client with typed methods
    index.ts        # Barrel export
  dto/
    data-contracts.ts  # DTO classes with decorators
  dist/             # Built output
  package.json
  tsconfig.json

Dependencies

Generated clients have minimal dependencies:

{
  "dependencies": {
    "axios": "^1.7.9"
  },
  "peerDependencies": {
    "@nestjs/swagger": "^7.4.2",
    "class-validator": "^0.14.1"
  }
}

Peer dependencies mean:

  • Frontend apps do not need to install NestJS packages
  • Backend services use their existing NestJS installation
  • No duplicate dependencies in your bundle