ngx-openapi-typescript

Type-safe Angular resource signals and HTTP client backed by openapi-typescript.

This library provides two main utilities:

• createOpenApiResource — a reactive factory built on Angular's httpResource that gives you compile-time type safety for every HTTP request and response shape defined in your OpenAPI schema.
• OpenApiHttpClient — a typed wrapper around Angular's HttpClient for imperative (non-reactive) HTTP calls.

Both are driven by the types generated by openapi-typescript, so typos in paths, wrong parameter names, or incorrect body shapes are caught at compile time, not at runtime.

Installation

npm install ngx-openapi-typescript openapi-typescript-helpers

This package is built for Angular ^21.2.0 and ^22.0.0 and expects these peer dependencies in your app:

• @angular/common ^21.2.0 || ^22.0.0
• @angular/core ^21.2.0 || ^22.0.0
• openapi-typescript-helpers ^0.1.0

If you want to generate types locally, also install the generator as a dev dependency:

npm install -D openapi-typescript

Generating types

Generate type definitions by pointing openapi-typescript at your OpenAPI spec:

npx openapi-typescript https://api.example.com/openapi.yaml -o src/api.types.ts

This creates a paths interface that both utilities consume.

API

createOpenApiResource

A factory for creating reactive Angular resource signals. Must be called inside an Angular injection context (component/service field initializer or constructor).

import type { paths } from './api.types';
import { createOpenApiResource } from 'ngx-openapi-typescript';

@Component({ ... })
export class PetListComponent {
  private readonly api = createOpenApiResource<paths>({
    baseUrl: 'https://api.example.com',
  });

  // Simple GET — no params required
  protected readonly pets = this.api('/pets');

  // Reactive GET with params — re-fetches when the signals read inside the lambda change
  protected readonly petsLimited = this.api('/pets', () => ({
    params: { query: { limit: 10 } },
  }));

  // Pass signal-driven path params — re-fetches when petId() changes
  private readonly petId = signal(1);
  protected readonly pet = this.api('/pets/{petId}', () => ({
    params: { path: { petId: this.petId() } },
  }));

  // Return undefined to put the resource in Idle state (no request made)
  private readonly enabled = signal(false);
  protected readonly lazyPets = this.api('/pets', () =>
    this.enabled() ? {} : undefined,
  );
}

Method Override

The factory defaults to GET. You can pass a method option to use a different HTTP method, but Angular recommends using httpResource only for reads. Prefer OpenApiHttpClient for mutations.

// Explicit method override (not recommended for production use)
protected readonly createResult = this.api('/pets', () => ({
  body: { name: 'Buddy' },
}), { method: 'post' });

OpenApiHttpClient

A base class that wraps Angular's HttpClient with OpenAPI types. Ideal for imperative calls, mutations, or service-layer code.

import type { paths } from './api.types';
import { OpenApiHttpClient } from 'ngx-openapi-typescript';
import { Injectable } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class PetApiClient extends OpenApiHttpClient<paths> {
  constructor() {
    super({ baseUrl: 'https://api.example.com' });
  }
}

// In a component/service
@Component({ ... })
export class PetDetailComponent {
  private readonly api = inject(PetApiClient);

  load(id: number) {
    this.api
      .get('/pets/{petId}', { params: { path: { petId: id } } })
      .subscribe(pet => console.log(pet)); // pet is typed as Pet
  }

  create(name: string) {
    this.api
      .post('/pets', { body: { name } })
      .subscribe(newPet => console.log(newPet));
  }
}

Development

# Build the library
ng build ngx-openapi-typescript

# Run tests
ng test ngx-openapi-typescript

# Start the demo app
ng serve demo