⚡Examples  •  📝Documentation  •  🐛Issues

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

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

# 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

• -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)

• 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'

• 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)

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.

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)

// 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],
});

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());
}

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();
    }
}

Add these scripts to your package.json:

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

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).

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.

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.