# @metaengine/openapi-angular

Generate TypeScript/Angular services and models from OpenAPI specifications.

## Install

```bash
npm install --save-dev @metaengine/openapi-angular
```

Or use directly with npx:

```bash
npx @metaengine/openapi-angular <input> <output>
```

## Requirements

- Node.js 14.0 or later
- .NET 8.0 or later runtime ([Download](https://dotnet.microsoft.com/download))
- Angular 14.0 or later (for generated code)

## Quick start

```bash
npx @metaengine/openapi-angular api.yaml ./src/app/api \
  --inject-function \
  --error-handling \
  --documentation
```

## CLI options

| Option | Description | Default |
|--------|-------------|---------|
| `--include-tags <tags>` | Filter by OpenAPI tags (comma-separated, case-insensitive) | - |
| `--provided-in <value>` | Angular injection scope (root, any, platform) | - |
| `--base-url-token <name>` | Injection token name for base URL | `BASE_URL` |
| `--options-threshold <n>` | Parameter count for options object | `4` |
| `--documentation` | Generate JSDoc comments | `false` |
| `--inject-function` | Use inject() instead of constructor injection | `false` |
| `--service-decorator [scope]` | Emit Angular 22 `@Service()` decorator instead of `@Injectable` (auto-enables inject()). `scope`: `auto-provided` (default) or `component-scoped` for `@Service({ autoProvided: false })` | - |
| `--http-resource` | Use httpResource with Signals for HTTP calls (Angular 19.2+) | `false` |
| `--lazy-resource` | Add trigger signal for lazy loading (implies `--http-resource`) | `false` |
| `--error-handling` | Enable smart error handling | `false` |
| `--strict-validation` | Enable strict OpenAPI validation | `false` |
| `--date-transformation` | Convert date strings in responses to Date objects | `false` |
| `--interceptors` | Generate Angular interceptors for cross-cutting concerns | `false` |
| `--types-barrel` | Emit an `index.ts` barrel per folder plus a root `index.ts` re-exporting everything | `false` |
| `--clean` | Clean output directory (remove files not in generation) | `false` |
| `--verbose` | Enable verbose logging | `false` |
| `--type-mapping <slug=target>` | Override TS type for an OpenAPI format. Repeatable. See [Type mapping overrides](#type-mapping-overrides) | - |
| `--help, -h` | Show help message | - |

## Type mapping overrides

Use `--type-mapping` to override the TS type emitted for a given OpenAPI `(type, format)` pair. Repeatable. Unknown slugs and unknown targets are hard errors.

| Slug | OpenAPI `(type, format)` | Default | `--type-mapping` value |
|------|--------------------------|---------|------------------------|
| `int64` | `(integer, int64)` | `number` | `int64=bigint` |
| `decimal` | `(number, decimal)` | `number` | `decimal=string` |
| `date-time` | `(string, date-time)` | `Date` | `date-time=string` |
| `date` | `(string, date)` | `Date` | `date=string` |

```bash
npx @metaengine/openapi-angular api.yaml ./src/app/api \
  --type-mapping int64=bigint \
  --type-mapping date-time=string
```

## See it live

Try the generator with your own spec at <https://www.metaengine.eu/converters>.

## License

MIT

## Support

For issues and feature requests, please visit:
https://github.com/meta-engine/openapi-angular/issues