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
• package - { name, version?, repository?, publishRegistry?, angularVersion?, packageJson? }; emits package.json, ng-package.json, tsconfig.json, README.md and .gitignore so the output builds with ng-packagr and publishes as a standalone Angular library (see the publishing guide)
• 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.

Maintainer

Created and maintained by Tareq Jami of Jami IT, a freelance software engineering practice in Hamburg, Germany. The library is MIT-licensed and stays that way; commercial support around it — OpenAPI and Angular integration work, migrations off hand-written clients, architecture review — goes through jami-it.de.

You can also sponsor the project on GitHub.