Generated Output

What ng-openapi actually writes into your output directory, file by file. This is the canonical reference for the generated structure — other pages link here instead of repeating it.

The Full Tree

With the default configuration (generateServices: true, dateType: "Date"):

<output>/
├── models/
│   ├── index.ts             # TypeScript interfaces, enums / unions
│   ├── *.ts                 # One file per schema (only with modelFileStructure: 'per-type')
│   └── request-params.ts    # Request-object interfaces (only with useSingleRequestParameter)
├── services/
│   ├── index.ts             # Service exports
│   └── *.service.ts         # One Angular service per controller/tag
├── tokens/
│   └── index.ts             # Injection tokens for this client
├── utils/
│   ├── base-interceptor.ts  # Routes client-scoped interceptors
│   ├── date-transformer.ts  # Date interceptor (only with dateType: "Date")
│   ├── file-download.ts     # Download helpers
│   └── http-params-builder.ts # Query-param serialization
├── providers.ts             # provide<ClientName>Client() setup function
└── index.ts                 # Main barrel export

Plugins add their own directories next to these:

• validators/ — Zod schemas, one file per controller (Zod plugin)
• resources/ — httpResource-based services (HTTP Resource plugin)

With generateServices: false only models/, the main index.ts, and any plugin directories are generated — plugins run regardless of this option. Pair that mode only with plugins whose output stands alone (Zod imports nothing but zod); the HTTP Resource plugin imports from tokens/ and utils/, which this mode does not generate.

File by File

models/index.ts

One interface per schema in the spec, plus enums in the style you chose via enumStyle. Date fields are typed Date or string depending on dateType. Type names can be decorated with a prefix/suffix via naming.models.

With modelFileStructure: 'per-type', each schema instead gets its own models/<kebab-name>.ts file (plus models/request-options.ts for the RequestOptions interface), and models/index.ts becomes a pure barrel re-exporting them — imports from ../models and the main index.ts are unaffected.

models/request-params.ts

Only generated with useSingleRequestParameter: one exported <MethodName>Params interface per operation, re-exported through the models barrel.

services/*.service.ts

One injectable service per controller (OpenAPI tag), using inject(HttpClient) and this client's base-path token. Class names default to <Tag>Service and can be decorated via naming.services (file names are unaffected). Classes are decorated with @Injectable({ providedIn: "root" }), or Angular 22+'s @Service() when serviceDecorator is set to 'service'. Method names come from operationId, optionally transformed by customizeMethodName. Tags and operationIds are free-form text in a valid spec, so characters that cannot appear in a TypeScript identifier are treated as word separators: the tag Groups (yes) yields GroupsYesService in groupsYes.service.ts, and the operationId groups_{group_id}_delete yields the method groupsGroupIdDelete. When validation.response is enabled, each method accepts a parse hook in its trailing options parameter.

tokens/index.ts

Injection tokens namespaced per client so multiple clients can coexist (see Multiple Clients):

• BASE_PATH_<CLIENTNAME> — the API base URL (falls back to /api)
• HTTP_INTERCEPTORS_<CLIENTNAME> — this client's interceptor instances
• CLIENT_CONTEXT_TOKEN_<CLIENTNAME> — HttpContext token marking which client a request belongs to

For the default client, deprecated BASE_PATH / CLIENT_CONTEXT_TOKEN aliases are kept for backwards compatibility.

utils/base-interceptor.ts

A global interceptor that checks each request's HttpContext and applies this client's interceptor chain only to requests made by this client's services — that's what keeps interceptors from leaking across clients.

utils/date-transformer.ts

Only generated with dateType: "Date". Contains ISO_DATE_REGEX, transformDates, and the DateInterceptor that converts ISO date strings in responses to Date objects. See the Date Transformer reference.

utils/file-download.ts

downloadFile, downloadFileOperator, and extractFilenameFromContentDisposition for handling blob downloads. See the File Download Helper reference.

utils/http-params-builder.ts

Serializes query parameters into HttpParams, handling arrays, nested objects, and Date values. Used internally by the generated services.

providers.ts

The provide<ClientName>Client() function (e.g. provideDefaultClient) plus its config interface. Wires up the base-path token, the base interceptor, client-scoped interceptors, and (with dateType: "Date") the date interceptor. See the Providers reference.

index.ts

Barrel export of everything above — including any plugin directories (e.g. resources/, validators/) — so consumers can import from the output root.

Schema References

• $ref to a whole schema (#/components/schemas/Pet) — an imported model in models/.
• $ref to a property inside a schema (#/components/schemas/PolicyEntry/properties/namespaces) — inlined at each use, no extra model.

An unresolvable or cyclic property $ref is left as-is and warned about:

⚠️ Could not resolve nested $ref "#/components/schemas/Missing/properties/nope". The generated type will not match the spec (generated files ship @ts-nocheck, so this surfaces as a silently wrong type rather than a compile error).

Your build stays green — that is the point of the warning. Generated files carry @ts-nocheck, so the dangling type name degrades to any instead of failing compilation, and the warning is the only signal that the API surface is wrong.

Fix the spec: promote the target to a named schema and reference that.

Only pointers under #/components/schemas/… and #/definitions/… are inlined. A deep pointer into any other root — #/components/responses/Error/content/application~1json/schema, #/paths/…/schema, Swagger 2.0 #/parameters/X/schema, the shape redocly bundle and swagger-cli bundle emit for a repeated subschema — is passed through and warned about, naming the type the output will contain so you can search for it:

⚠️ Nested $ref "#/components/responses/Error/content/application~1json/schema" points into a part of the document this generator does not inline (only #/components/schemas/… and #/definitions/… are) — it will be emitted as the type "Schema", which nothing defines. Promote the target to a named schema and reference that. …

Regeneration Notes

• Every file starts with a "Generated by ng-openapi — do not edit" header; regeneration overwrites them, so put customizations in your own code (interceptors, wrappers), never in the output directory.
• Generated files carry @ts-nocheck and eslint-disable pragmas so they don't fight your project's lint/strict settings.
• Add the output directory to your API-generation script rather than committing manual tweaks — see CLI Usage for workflow recipes.