Angular OpenAPI Client Generator

💪 Made with ❤️ by Angular Devs for Angular Devs

⚡Examples  •  📝Documentation  •  🐛Issues

Installation

npm install ng-openapi --save-dev
# or
yarn add ng-openapi --dev

CLI Usage

Using a Configuration File (Recommended)

Create a configuration file (e.g., openapi.config.ts):

import { GeneratorConfig } from "ng-openapi";

const config: GeneratorConfig = {
    input: "./swagger.json",
    output: "./src/api",
    options: {
        dateType: "Date",
        enumStyle: "enum",
        generateEnumBasedOnDescription: true,
        generateServices: true,
        customHeaders: {
            "X-Requested-With": "XMLHttpRequest",
            Accept: "application/json",
        },
        responseTypeMapping: {
            "application/pdf": "blob",
            "application/zip": "blob",
            "text/csv": "text",
        },
        customizeMethodName: (operationId) => {
            const parts = operationId.split("_");
            return parts[parts.length - 1] || operationId;
        },
    },
};

export default config;

Then run:

# Direct command
ng-openapi -c openapi.config.ts

# Or with the generate subcommand
ng-openapi generate -c openapi.config.ts

Using Command Line Options

# Generate both types and services
ng-openapi -i ./swagger.json -o ./src/api

# Generate only types
ng-openapi -i ./swagger.json -o ./src/api --types-only

# Specify date type
ng-openapi -i ./swagger.json -o ./src/api --date-type string

Command Line Options

• -c, --config <path> - Path to configuration file
• -i, --input <path> - Path to Swagger/OpenAPI specification file
• -o, --output <path> - Output directory (default: ./src/generated)
• --types-only - Generate only TypeScript interfaces
• --date-type <type> - Date type to use: string or Date (default: Date)

Configuration Options

Required Fields

• input - Path or URL to your Swagger/OpenAPI specification (.json, .yaml, .yml)
• output - Output directory for generated files
• options.dateType - How to handle date types: 'string' or 'Date'
• options.enumStyle - Enum generation style: 'enum' or 'union'

Optional Fields

• clientName - Unique identifier for this client; names the generated provider function and tokens (default: 'default')
• validateInput - Custom acceptance check (spec) => boolean; returning false aborts generation
• plugins - Plugin generator classes (e.g. HttpResourcePlugin, ZodPlugin), run after core generation
• compilerOptions - TypeScript compiler options for code generation
• options.generateServices - Generate Angular services (default: true)
• options.generateEnumBasedOnDescription - Parse enum values from description field (default: false)
• options.validation - { response?: boolean }; adds a parse hook to generated methods for response validation
• options.customHeaders - Headers to add to all HTTP requests
• options.responseTypeMapping - Map content types to Angular HttpClient response types
• options.customizeMethodName - Function to customize generated method names
• options.useSingleRequestParameter - Generate one request object parameter per method instead of positional parameters (default: false)

Generated Files Structure

output/
├── models/
│   └── index.ts        # TypeScript interfaces/types
├── services/
│   ├── index.ts        # Service exports
│   └── *.service.ts    # Angular services
├── tokens/
│   └── index.ts        # Injection tokens
├── utils/
│   ├── base-interceptor.ts    # Client-scoped interceptor routing
│   ├── date-transformer.ts    # Date interceptor (dateType: "Date" only)
│   ├── file-download.ts       # File download helpers
│   └── http-params-builder.ts # Query-param serialization
├── providers.ts        # Provider functions for easy setup
└── index.ts           # Main exports

See Generated Output for what every file does.

Angular Integration

🚀 Easy Setup (Recommended)

The simplest way to integrate ng-openapi is using the provider function:

// In your app.config.ts
import { ApplicationConfig } from "@angular/core";
import { provideDefaultClient } from "./api/providers";

export const appConfig: ApplicationConfig = {
    providers: [
        // One-line setup with automatic interceptor configuration
        provideDefaultClient({
            basePath: "https://api.example.com",
        }),
        // other providers...
    ],
};

The provider function is named after your clientName (e.g. clientName: "PetStore" → providePetStoreClient); without a clientName it is provideDefaultClient.

That's it! This automatically configures:

• ✅ BASE_PATH token
• ✅ Date transformation interceptor (if using Date type)

Advanced Provider Options

// Disable date transformation
provideDefaultClient({
    basePath: "https://api.example.com",
    enableDateTransform: false,
});

// Client-specific interceptors (classes, not instances)
provideDefaultClient({
    basePath: "https://api.example.com",
    interceptors: [AuthInterceptor, LoggingInterceptor],
});

Using Generated Services

import { Component, inject } from "@angular/core";
import { toSignal } from "@angular/core/rxjs-interop";
import { UserService } from "./api/services";
import { User } from "./api/models";

@Component({
    selector: "app-users",
    template: `...`,
})
export class UsersComponent {
    private readonly userService = inject(UserService);
    readonly users = toSignal(this.userService.getUsers());
}

File Download Example

import { Component, inject } from "@angular/core";
import { downloadFileOperator } from "./api/utils/file-download";

export class ReportComponent {
    private readonly reportService = inject(ReportService);

    downloadReport() {
        this.reportService.getReport("pdf", { reportId: 123 }).pipe(downloadFileOperator("report.pdf")).subscribe();
    }
}

Package.json Scripts

Add these scripts to your package.json:

{
    "scripts": {
        "generate:api": "ng-openapi -c openapi.config.ts"
    }
}

Using AI Assistants?

Point your AI coding assistant (Claude Code, Cursor, Copilot, …) at https://ng-openapi.dev/llms.txt — it contains usage rules that prevent the most common integration mistakes, plus links into the full documentation (https://ng-openapi.dev/llms-full.txt for everything in one file).

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup and test workflows, and ARCHITECTURE.md for how the generation pipeline is structured and where new code should go.