@voyagerpoland/proxy-gen

CLI tool that generates TypeScript DTOs and Angular ServiceProxy facades from an OpenAPI JSON spec. Part of the @voyagerpoland/proxy ecosystem.

Installation

npm install -D @voyagerpoland/proxy-gen

Quick start

npx voyager-proxy-gen --input swagger.json --output src/app/api/generated

Output:

@voyagerpoland/proxy-gen
  Input:  swagger.json
  Output: src/app/api/generated

✓ Generated 4 models, 1 services (9 files)

Generated file structure

src/app/api/generated/
├── models/
│   ├── product.ts                 ← export interface Product { ... }
│   ├── create-product-request.ts
│   ├── ...
│   └── index.ts                   ← barrel export
├── services/
│   ├── product-service.ts         ← class ProductService extends ServiceProxy
│   └── index.ts                   ← barrel export
├── api-config.ts                  ← InjectionToken<string> API_BASE_URL
└── index.ts                       ← top-level barrel export

Generated service

// AUTO-GENERATED by @voyagerpoland/proxy-gen — DO NOT EDIT

@Injectable({ providedIn: 'root' })
export class ProductService extends ServiceProxy {
  constructor() {
    super(inject(HttpClient), inject(API_BASE_URL));
  }

  listProducts(category: string, limit: number): ResultAsync<ProductListResponse> {
    return this.get<ProductListResponse>('/api/products', {
      params: { category, limit: limit.toString() },
    });
  }

  getProduct(id: number): ResultAsync<Product> {
    return this.get<Product>(`/api/products/${id}`);
  }

  createProduct(body: CreateProductRequest): ResultAsync<Product> {
    return this.post<Product>('/api/products', body);
  }

  deleteProduct(id: number): ResultAsync<void> {
    return this.del(`/api/products/${id}`);
  }
}

Every generated method returns ResultAsync<T> and inherits retry (3×), circuit breaker, and timeout behaviour from ServiceProxy.

Generated model

// AUTO-GENERATED by @voyagerpoland/proxy-gen — DO NOT EDIT

export interface Product {
  readonly id?: number;
  readonly name?: string | null;
  readonly price?: number;
}

OpenAPI → TypeScript type mapping

| OpenAPI | TypeScript | | ------------------------------ | --------------------------------------- | | integer / number | number | | string | string | | string + format: date-time | string (ISO 8601) | | boolean | boolean | | array + items | T[] | | nullable: true | T \| null | | $ref | named import | | enum | 'a' \| 'b' (union) or enum (option)| | allOf | extends / intersection |

CLI reference

Usage: voyager-proxy-gen [options]

Options:
  --input, -i <path>       Path to OpenAPI JSON spec (required unless --config)
  --output, -o <path>      Output directory for generated files (required unless --config)
  --config, -c <path>      Path to config JSON file
  --enum-style <style>     Enum style: "union" (default) or "enum"
  --base-url-token <name>  InjectionToken name (default: "API_BASE_URL")
  --service-suffix <name>  Service class suffix (default: "Service")
  --help, -h               Show this help message
  --version, -v            Show version

Config file

Instead of CLI flags you can create a voyager-proxy-gen.json config file:

{
  "$schema": "node_modules/@voyagerpoland/proxy-gen/schema.json",
  "input": "swagger.json",
  "output": "src/app/api/generated",
  "enumStyle": "union",
  "baseUrlToken": "API_BASE_URL",
  "serviceNameSuffix": "Service"
}

Then just run:

npx voyager-proxy-gen --config voyager-proxy-gen.json

Or with auto-discovery (no flags needed when the file is named voyager-proxy-gen.json):

npx voyager-proxy-gen

Config options

| Option | CLI flag | Default | Description | | ------------------- | -------------------- | ---------------- | ------------------------------------------------ | | input | --input, -i | — | Path to the OpenAPI JSON spec (required) | | output | --output, -o | — | Output directory for generated files (required) | | enumStyle | --enum-style | "union" | "union" ('a' \| 'b') or "enum" (TS enum) | | baseUrlToken | --base-url-token | "API_BASE_URL" | Angular InjectionToken name for the base URL | | serviceNameSuffix | --service-suffix | "Service" | Suffix appended to generated service class names |

npm script integration

Add a script to your package.json:

{
  "scripts": {
    "generate-api": "voyager-proxy-gen --input swagger.json --output src/app/api/generated"
  }
}

Then regenerate any time the backend spec changes:

npm run generate-api

Providing the base URL in Angular

The generated api-config.ts exports an InjectionToken. Provide its value in app.config.ts:

import { API_BASE_URL } from './api/generated/api-config';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    { provide: API_BASE_URL, useValue: 'https://api.example.com' },
  ],
};

Requirements

• Node.js ≥ 18
• Generated code targets Angular 17+ with @voyagerpoland/proxy and @voyagerpoland/results

License

MIT