npm NuGet v1.3.1 MIT

OpenAPI to Angular Client Generator

@metaengine/openapi-angular

Convert OpenAPI 3.x to Angular services and models with httpResource, Signals, inject() DI, and the new Angular 22 @Service() decorator. Generates idiomatic Angular 19+ code with reactive data fetching.

OpenAPI 3.xMetaEngine IRTypeScript · Angular
Convert OpenAPI to Angular in the browser
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

npmPrimary@metaengine/openapi-angular
$npm install @metaengine/openapi-angular
v1.3.1
NuGetMetaEngine.TypeScript.OpenApi.Angular
$dotnet add package MetaEngine.TypeScript.OpenApi.Angular
v1.3.1
Usage

Drive it from the CLI or programmatically

npm ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

npm · npx · CI-friendly

After install, point the CLI at your schema. It writes the generated tree to your chosen output directory.

Basic syntax
terminal
npx @metaengine/openapi-angular <input> <output> [options]

Supports OpenAPI 3.0+ specifications in both JSON and YAML formats.

Quick examples
Generate from a local file
npx @metaengine/openapi-angular api.yaml ./src/app/api
Generate from a URL
npx @metaengine/openapi-angular https://api.example.com/openapi.json ./src/app/api
With Angular best practices
npx @metaengine/openapi-angular api.yaml ./src/app/api \
  --provided-in root \
  --documentation \
  --error-handling \
  --inject-function
With the Angular 22 @Service() decorator
npx @metaengine/openapi-angular api.yaml ./src/app/api \
  --service-decorator \
  --http-resource \
  --documentation
CLI options
Option
Description
--provided-in <value>
Angular injection scope (root, any, platform)
--base-url-token <name>
Injection token name for base URL [default: BASE_URL]
--options-threshold <n>
Parameter count to use options object [default: 4]
--documentation
Generate JSDoc comments
--inject-function
Use inject() instead of constructor injection (Angular 14+)
--service-decorator [scope]
Emit the Angular 22 @Service() decorator instead of @Injectable (auto-enables inject()). scope: auto-provided (default) or component-scoped for @Service({ autoProvided: false })
--http-resource
Generate httpResource methods with Signals for GET operations (Angular 19.2+)
--lazy-resource
Add optional trigger signal for lazy loading of httpResource methods (implies --http-resource)
--interceptors
Generate Angular HTTP interceptors so cross-cutting concerns (auth, retries, error handling) live in interceptors instead of inline per-service code
--error-handling
Enable smart error handling
--type-mapping <mapping>
Override TS type for an OpenAPI format. Repeatable. int64=bigint · decimal=string · date-time=string · date=string
--include-tags <tags>
Filter by OpenAPI tags (comma-separated, case-insensitive)
--strict-validation
Enable strict OpenAPI validation
--date-transformation
Convert date strings in responses to JavaScript Date objects
--clean
Remove files no longer part of generation while preserving unchanged files (smart VCS-friendly cleanup)
--verbose
Enable verbose logging
--help, -h
Show help message
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method, and most are also exposed as CLI flags. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

Angular Options

12
  • WithBaseUrlToken(string)Injection token name for base URL (default: "BASE_URL")
  • WithInjectFunction()Use inject() instead of constructor DI (Angular 14+)
  • WithProvidedIn(string)Injection scope ("root", "platform", "any")
  • WithServiceDecorator()Emit the Angular 22 @Service() decorator instead of @Injectable — a root-provided singleton that auto-enables inject() DI (mutually exclusive with WithProvidedIn, last wins)
  • WithServiceDecorator(x => x.ComponentScoped())Angular 22 @Service({ autoProvided: false }) — a manually-provided, component/route-scoped service
  • WithHttpResources()Generate httpResource methods with Signals for GET operations (Angular 19.2+)
  • WithHttpResources(r => r.WithTrigger())Add optional trigger signal for lazy loading of httpResource methods
  • WithInterceptors()Generate Angular HTTP interceptors so cross-cutting concerns (auth, retries, error handling) live in interceptors instead of inline per-service code
  • WithResponseDateTransformation()Convert date / date-time strings in responses to Date objects
  • WithMethodNames(Func)Custom method naming rule
  • WithDocumentation()Enable JSDoc comments
  • WithOptionsObjectThreshold(int)Parameter count for options object (default: 4)

Auth · Headers · Resilience

12
  • WithErrorHandling()Enable smart error handling based on HTTP status semantics
  • WithErrorHandling(errors => errors...)Per-status routing: ReturnNullFor(404, 403) · ReturnErrorFor(400, 422) · ThrowFor(401, 500)
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds Authorization header
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token with custom header name (e.g. X-Api-Key)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithTimeout(double)Request timeout in seconds for all operations
  • WithTimeout(double?, double?, double?, double?)Granular timeout: seconds · connect · read · write
  • WithRetries()Retries with exponential backoff (default status 429, 503)
  • WithRetries(int)Retries with a custom max-attempts count
  • WithRetries(int, double, double, int[])Retries with full custom settings including status codes

OpenAPI Filtering

3
  • WithStrictValidation()Enable strict OpenAPI validation
  • WithOperationFilter(Func)Filter operations by predicate
  • WithHeaderFilter(Func)Filter header parameters

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

2
  • Verbose()Enable verbose logging
  • WithLogger(Action<string>)Route generation log output to a custom sink
Features

Why this package is different

Tree-shakeable
One file per tag (or per operation) means bundlers drop unused clients at build time. No runtime dispatch table.
Strict, no any
Output compiles under strict with no any. Unions, nullability and enums are modelled precisely so tsc catches drift.
Zero runtime
The default emit is types plus a thin client — no decorators, no reflection, no dependency surface beyond your HTTP lib.
Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Flexible naming
Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.