Generate signal-native, tree-shakeable API clients from any OpenAPI spec — in one command.

You have an OpenAPI spec. Your Angular app needs to call those endpoints. What do you do?

The usual answer is one of these:

• Write HttpClient calls by hand in a service, duplicating type information already in the spec
• Use a generic codegen tool that emits a 2,000-line service class full of endpoints you'll never call
• Spend a sprint wiring up interceptors, managing base URLs, and keeping types in sync

There's a better way. @constantant/openapi-resource-gen is an Nx generator that reads your OpenAPI 3.x spec and emits one typed InjectionToken per endpoint — each in its own file, each powered by Angular 22's httpResource(). You only bundle what you actually inject.

Requirements: Angular 22+ · Nx 22+

Why one token per endpoint?

The key insight is about tree-shaking. esbuild (Angular's bundler) tree-shakes at file boundaries. If find-pets-by-status.token.ts is never imported, the entire file — including its types and URL logic — costs zero bytes in your production bundle.

A traditional service class is one file with 50 methods. Import it once anywhere and you get all 50. With one token per file, you get only the endpoints you inject.

There's a second benefit: each generated token is a factory that returns an httpResource(). That means your HTTP calls are signal-native from the start — reactive params, automatic re-fetching on signal changes, .value() / .isLoading() / .error() signals — no RxJS, no subscriptions, no manual change detection.

Before and after

Here's the pattern most Angular developers write today:

// ❌ The old way: a hand-written service
@Injectable({ providedIn: 'root' })
export class PetService {
  private http = inject(HttpClient);
  private base = 'https://petstore3.swagger.io/api/v3';

  findByStatus(status: 'available' | 'pending' | 'sold') {
    return this.http.get<Pet[]>(`${this.base}/pet/findByStatus`, {
      params: { status },
    });
  }
}

// Component has to manage an Observable, a subscription, loading state, error state...
@Component({ ... })
export class PetsPageComponent {
  private petService = inject(PetService);
  pets = signal<Pet[]>([]);
  loading = signal(false);
  error = signal<string | null>(null);
  status = signal<'available' | 'pending' | 'sold'>('available');

  constructor() {
    effect(() => {
      this.loading.set(true);
      this.petService.findByStatus(this.status()).subscribe({
        next: (data) => { this.pets.set(data); this.loading.set(false); },
        error: (err) => { this.error.set(err.message); this.loading.set(false); },
      });
    });
  }
}

Problems with this pattern:

• Types are hand-written and will drift from the spec
• Loading/error state is boilerplate you write every time
• Effect + subscribe combination has subtle cancellation bugs
• The service is never tree-shaken — every endpoint ships, used or not

Here's the generated version:

// ✅ The generated way: inject and call
@Component({ ... })
export class PetsPageComponent {
  private findPetsByStatus = inject(FIND_PETS_BY_STATUS);

  readonly status = signal<'available' | 'pending' | 'sold'>('available');

  // Re-fetches automatically whenever status() changes
  readonly pets = this.findPetsByStatus(() => ({ status: this.status() }));
}

@if (pets.isLoading()) {
  <mat-progress-bar mode="indeterminate" />
}

@for (pet of pets.value() ?? []; track pet.id) {
  <p>{{ pet.name }} — {{ pet.status }}</p>
}

@if (pets.error()) {
  <p class="error">Something went wrong</p>
}

The loading state, error state, and reactive re-fetching come for free. The types come from the spec. Nothing is hand-written.

Setup walkthrough

Step 1 — install

npm install -D @constantant/openapi-resource-gen

Step 2 — generate

Point the generator at a local file or any HTTPS URL — no curl pre-step needed:

npx nx g @constantant/openapi-resource-gen:api-resource \
  --specPath=https://petstore3.swagger.io/api/v3/openapi.yaml \
  --outputDir=libs/petstore-data-access/src \
  --baseUrlToken=PETSTORE_BASE_URL \
  --includeMocks \
  --specId=petstore

That's it. The generator downloads the spec, validates it, runs openapi-typescript to produce a schema.d.ts, dereferences all $ref chains with @apidevtools/swagger-parser, and emits one token file per endpoint.

Step 3 — what you get

libs/petstore-data-access/src/
  schema.d.ts                     ← openapi-typescript output — never touch this
  api-base-url.token.ts           ← InjectionToken<string> for the base URL
  index.ts                        ← barrel — re-exports everything

  pet/
    find-pets-by-status.token.ts  ← one file per endpoint
    add-pet.token.ts
    update-pet.token.ts
    delete-pet.token.ts
    get-pet-by-id.token.ts
    ...

  store/
    ...

  user/
    ...

Endpoints are grouped into subfolders by OpenAPI tag. Each folder gets its own index.ts barrel. The root barrel re-exports everything.

Step 4 — wire up providers

// app.config.ts
import { provideHttpClient } from '@angular/common/http';
import {
  PETSTORE_BASE_URL,
  provideFindPetsByStatus,
  provideGetPetById,
} from '@myapp/petstore-data-access';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    { provide: PETSTORE_BASE_URL, useValue: 'https://petstore3.swagger.io/api/v3' },
    provideFindPetsByStatus(),
    provideGetPetById(),
    // Only register tokens you actually use — everything else is tree-shaken away
  ],
};

Step 5 — inject and use

@Component({ ... })
export class PetsPageComponent {
  private findPetsByStatus = inject(FIND_PETS_BY_STATUS);

  readonly status = signal<'available' | 'pending' | 'sold'>('available');
  readonly pets = this.findPetsByStatus(() => ({ status: this.status() }));
}

Step 6 — declare a generate target for easy re-runs

When your spec changes, you want to re-run the generator without remembering the full command. Add a target to project.json:

{
  "targets": {
    "generate": {
      "executor": "@constantant/openapi-resource-gen:generate",
      "options": {
        "specPath": "https://petstore3.swagger.io/api/v3/openapi.yaml",
        "outputDir": "libs/petstore-data-access/src",
        "baseUrlToken": "PETSTORE_BASE_URL",
        "includeMocks": true,
        "specId": "petstore"
      }
    }
  }
}

Now regeneration is just:

npx nx run petstore-data-access:generate

The generator tracks stale files and deletes any .token.ts that no longer corresponds to an endpoint in the spec. No phantom exports accumulate.

The generated token in detail

Every generated file follows the same structure. Here's a GET endpoint with query params:

// libs/petstore-data-access/src/pet/find-pets-by-status.token.ts

import { InjectionToken, inject, FactoryProvider } from '@angular/core';
import { httpResource } from '@angular/common/http';
import type { paths } from '../schema.d';
import { PETSTORE_BASE_URL } from '../api-base-url.token';

// Types sourced directly from the spec — zero hand-written interfaces
export type FindPetsByStatusParams =
  paths['/pet/findByStatus']['get']['parameters']['query'];
export type FindPetsByStatusResponse =
  paths['/pet/findByStatus']['get']['responses']['200']['content']['application/json'];

export const FIND_PETS_BY_STATUS = new InjectionToken<
  (params?: FindPetsByStatusParams | (() => FindPetsByStatusParams | undefined))
    => ReturnType<typeof httpResource<FindPetsByStatusResponse>>
>('FIND_PETS_BY_STATUS');

export function provideFindPetsByStatus(): FactoryProvider {
  return {
    provide: FIND_PETS_BY_STATUS,
    useFactory: () => {
      const base = inject(PETSTORE_BASE_URL);
      return (params?) =>
        httpResource<FindPetsByStatusResponse>(() => {
          const _params = typeof params === 'function' ? params() : params;
          if (typeof params === 'function' && _params === undefined) return undefined;
          return {
            url: `${base}/pet/findByStatus`,
            params: _params as any,
          };
        });
    },
  };
}

Three things worth noting in this generated code:

Block-body reactive lambda, not shorthand. The lambda uses () => { ... return { url } } rather than () => ({ url }). This is deliberate — a shorthand arrow always returns an object, so httpResource always fires. The block form can return undefined to suppress the request entirely, keeping the resource idle.

Types sourced from paths[...]. The query param type and response type both come from the generated schema.d.ts. If your spec changes and you regenerate, the types update automatically. There's no separate interface to maintain.

inject() inside the factory, not in a constructor. The token is fully compatible with Angular's tree-shaking rules — it can be providedIn: 'root' with no side effects on bundle size for tokens that are never injected.

Patterns you'll use every day

Reactive params — re-fetch when a signal changes

readonly statusFilter = signal<'available' | 'pending' | 'sold'>('available');

// Automatically re-fetches when statusFilter() changes
readonly pets = this.findPetsByStatus(() => ({ status: this.statusFilter() }));

No switchMap. No takeUntilDestroyed. The reactive lambda inside httpResource re-runs whenever a signal it reads changes — the same mechanism Angular uses for computed().

Conditional requests — suppress until conditions are met

readonly query = signal('');
readonly apiKey = signal<string | null>(null);

// No HTTP request fires until both query and apiKey are truthy
readonly results = this.youtubeSearch(() =>
  this.query() && this.apiKey()
    ? { q: this.query(), key: this.apiKey()!, part: 'snippet', maxResults: 10 }
    : undefined
);

When the thunk returns undefined, the resource stays in 'idle' — .isLoading() is false, .value() is undefined. When the signals change so the thunk returns a value, the first request fires automatically.

Path params

Path params (/pet/{petId}) become required positional arguments:

// Inject by petId input
readonly pet = this.getPetById(this.petId);

// Or as a reactive thunk when you need to combine with query params
readonly pet = this.getPetById(() => this.petId());

Mutations (POST / PUT / DELETE)

Mutation tokens accept a body. Pass a signal for reactive mutations, or use a thunk to suppress until the user submits:

readonly pendingPet = signal<AddPetBody | null>(null);

// No request until user clicks Submit
readonly result = this.addPet(() => this.pendingPet() ?? undefined);

onSubmit(pet: AddPetBody): void {
  this.pendingPet.set(pet);
}

Security — signals all the way down

When the spec declares a bearerAuth or oauth2 scheme, the generator emits an InjectionToken<Signal<string | null>>. Every endpoint token injects it optionally and reads the signal inside its reactive lambda — changing the auth token automatically re-fires all resources that use it.

// oauth2.security-token.ts (generated)
export const OAUTH2 = new InjectionToken<Signal<string | null>>('OAUTH2');

// In your auth logic:
onLoginSuccess(accessToken: string): void {
  this.token.set(accessToken);
  // Every resource that reads OAUTH2 re-fires automatically
}

No interceptor reloads, no manual refresh() calls.

Sharing a resource across components

Each call to the factory creates an independent httpResource. To share one resource across multiple components, hoist it into a root-scoped store token:

export const PETS_STORE = new InjectionToken('PETS_STORE', {
  providedIn: 'root',
  factory: () => {
    const findPetsByStatus = inject(FIND_PETS_BY_STATUS);
    const statusFilter = signal<'available' | 'pending' | 'sold'>('available');
    return {
      statusFilter,
      pets: findPetsByStatus(() => ({ status: statusFilter() })),
    };
  },
});

One HTTP request, shared across every component that injects PETS_STORE.

Testing without infrastructure

The companion package @constantant/openapi-resource-mocks ships a /testing sub-entry designed for Vitest and Jasmine component tests. It does not set up a mock bus, touch window, or emit DOM events — it replaces a token's factory with a signal-based mock and gives you assertion helpers.

import { mockResource } from '@constantant/openapi-resource-mocks/testing';

describe('PetsPageComponent', () => {
  let petsMock: ReturnType<typeof mockResource<FindPetsByStatusResponse>>;

  beforeEach(() => {
    petsMock = mockResource(FIND_PETS_BY_STATUS);

    TestBed.configureTestingModule({
      imports: [PetsPageComponent],
      providers: [petsMock], // MockResourceHandle is a FactoryProvider — drop it in directly
    });
  });

  it('renders pets when data arrives', async () => {
    const fixture = TestBed.createComponent(PetsPageComponent);
    fixture.detectChanges();

    petsMock.ref.resolve([{ id: 1, name: 'Rex', status: 'available', photoUrls: [] }]);
    fixture.detectChanges();

    const rows = fixture.nativeElement.querySelectorAll('.pet-row');
    expect(rows.length).toBe(1);
  });

  it('shows loading skeleton', async () => {
    petsMock = mockResource(FIND_PETS_BY_STATUS, { loading: true });
    // ...
  });

  it('shows error state', async () => {
    petsMock = mockResource(FIND_PETS_BY_STATUS, { error: new Error('503') });
    // ...
  });
});

You can also test multi-step scenarios — pagination, retry-then-succeed, error-then-recover — using a sequence:

petsMock = mockResource(FIND_PETS_BY_STATUS, {
  sequence: [
    { error: new Error('timeout') },    // first call fails
    { error: new Error('timeout') },    // retry also fails
    { value: [{ id: 1, name: 'Rex', ... }] }, // third succeeds
  ],
});

The DevTools extension — live mock control without code changes

Generate with --includeMocks and you unlock something beyond testing: the OpenAPI Resource Mocks DevTools Chrome extension.

Install it (currently via Load unpacked while the Chrome Web Store review completes):

git clone https://github.com/constantant/angular-openapi-gen.git
cd angular-openapi-gen && npm ci
npx nx run openapi-resource-devtools:build
# Then: chrome://extensions → Developer mode → Load unpacked → dist/tools/openapi-resource-devtools/

Your app needs provideMockResourceBus() in its providers — typically in a mock build configuration you run locally:

// app.config.mock.ts
import { provideMockResourceBus } from '@constantant/openapi-resource-mocks';
import * as mocks from '@myapp/petstore-data-access/mock';

export const mockAppConfig: ApplicationConfig = {
  providers: [
    provideMockResourceBus(),
    mocks.provideFindPetsByStatusMock(),
    mocks.provideAddPetMock(),
  ],
};

Open Chrome DevTools on the running app and an API Mocks tab appears. From there you can:

Control mock state without touching code. Click Resolve, Fail, or Loading on any token row. Set a delay. Reset to idle. All without a page reload.

Catch requests before they resolve. Enable catch mode on a token and the next request from that component is held in CAUGHT state. The Respond tab shows exactly what params the component sent. Fill in a response JSON and click Release. This is the fastest way to test loading skeletons and error states for deeply conditional UI.

Import your spec for schema-aware features. Import mocks.manifest.json (generated alongside your tokens) or the full OpenAPI YAML/JSON. With the spec loaded, the Respond tab gains ⚡ Example (generates a valid random payload from the response schema) and ✓ Validate (checks your JSON against the schema before releasing).

Save and load scenarios. Snapshot the entire mock table state — values and catch modes — as a named scenario. Share the JSON with teammates so anyone can reproduce the exact UI state you're reviewing. Commit it alongside a PR to make bug reproductions reproducible.

Create local mocks before the code exists. The ＋ New mock button lets you create a panel-managed entry for an operation you haven't implemented yet. Configure its catch mode and response while you write the Angular component. When provideMockResource() is eventually registered by the app, the local entry is promoted in-place — your configuration carries over.

One particularly useful detail: catch mode survives page navigation. The background service worker injects window.__oarmPendingCatch__ into the page before Angular's module scripts execute, so the very first request during bootstrap is caught — not just user-triggered ones.

Generator options reference

How it compares to the alternatives

There are four established tools Angular teams reach for when generating API clients from an OpenAPI spec. Here's how they each work — and where the trade-offs land.

Quick reference

OpenAPI Generator — @openapitools/openapi-generator-cli

The most widely used tool in the ecosystem, with a typescript-angular template that emits one @Injectable({ providedIn: 'root' }) service per API tag. Each method returns an Observable<T>.

The core problem for modern Angular apps is that class-based services are not tree-shakeable at the endpoint level. A long-standing GitHub issue (#11654) tracks exactly this: the angular template bundles every generated method regardless of which ones are actually called. For a GitHub or YouTube API with hundreds of operations, that means a lot of dead code in production.

The second problem is the Observable surface. You end up writing toSignal() adapters, managing takeUntilDestroyed(), and wiring up loading/error state manually — all boilerplate that httpResource already handles.

NSwag

NSwag takes the same class-per-tag approach, but its primary audience is .NET + ASP.NET Core shops where the spec comes from a .NET backend and the tooling integrates with MSBuild. For Angular teams without a .NET backend, the configuration overhead (an nswag.json file, NSwag Studio on Windows) adds friction without much return.

The generated output looks similar to OpenAPI Generator: @Injectable service, Observable methods, generated TypeScript interfaces. No signal support, no per-endpoint tree-shaking, no mock story beyond what you build yourself.

orval

Orval is the most actively evolving of the three established tools. It targets multiple frameworks (React Query, SWR, Axios, Angular) and has recently added an httpResource output mode — when enabled, it emits a sibling *.resource.ts file alongside the main *.service.ts.

This is a meaningful step forward, but the architecture remains additive: the Observable service is still the primary output, and httpResource is layered on top. You get both files whether you need them or not. The underlying output unit is still a service class per tag, so tree-shaking is at the class level, not the endpoint level.

Orval's strongest area is mock generation: it has solid MSW 2.x handler output, and its mock approach is well-documented. If your team is already on MSW and happy with Observable-based services, orval is a reasonable choice.

hey-api/openapi-ts

The most modern of the three, with an ESM-first approach and a "flat SDK" mode where individual functions (rather than a class) are emitted per operation. Flat mode supports tree-shaking — unused operations are not included in the bundle.

The catch is that hey-api/openapi-ts is framework-agnostic. It generates fetch/XHR clients, not Angular HttpClient calls, which means you lose Angular's interceptor chain, HttpClientTestingModule, and — most importantly — httpResource. You'd need to wrap the generated functions to integrate them with Angular's DI and signal system, at which point you're writing the glue code that the generator was supposed to eliminate.

There have also been active bugs with the Angular client output due to how it handles this references in arrow-function service files.

The fundamental difference

Every tool above generates from the same starting point: "here is an API tag, emit the methods for it." The output unit is the tag (or the whole API), and tree-shaking has to happen downstream — if at all.

openapi-resource-gen starts from a different premise: the right unit is the endpoint. One file, one token, one httpResource. esbuild's tree-shaking works at file boundaries. If you never inject(FIND_PETS_BY_STATUS), that file is never imported, and none of its code — URL string, type aliases, factory function — ships in your bundle.

The other difference is depth. The other tools stop at code generation. openapi-resource-gen ships with a mock bus for Playwright E2E, a /testing sub-entry for Vitest/Jasmine component tests, and a Chrome DevTools extension that lets you control mock state, catch in-flight requests, generate schema-valid example payloads, and share reproducible mock scenarios across your team — without touching code or reloading the page.

The philosophy: the right unit of tree-shaking is the endpoint, not the API.

Try it

npm install -D @constantant/openapi-resource-gen

npx nx g @constantant/openapi-resource-gen:api-resource \
  --specPath=https://petstore3.swagger.io/api/v3/openapi.yaml \
  --outputDir=libs/petstore-data-access/src \
  --baseUrlToken=PETSTORE_BASE_URL

• npm: @constantant/openapi-resource-gen · @constantant/openapi-resource-mocks
• GitHub: constantant/angular-openapi-gen
• Full docs: docs/README.md

Contributions are welcome — see CONTRIBUTING.md.

Built with Angular 22 · Nx · httpResource · openapi-typescript