dtolator

Code generator that converts OpenAPI schemas, plain JSON, and JSON Schema files into typed code for multiple languages and frameworks.

Supported outputs

Installation

Install with uv (recommended) — it fetches the prebuilt binary from PyPI and puts it on your PATH:

uv tool install dtolator

To upgrade later:

uv tool upgrade dtolator

Or download the latest executable from the GitHub Releases page and place it on your PATH.

Or install via Cargo:

cargo install --git https://github.com/vivainio/dtolator

Or build from source:

git clone https://github.com/vivainio/dtolator
cd dtolator
cargo build --release

Usage

# Zod schemas to stdout (default)
dtolator --from-openapi schema.json

# TypeScript interfaces to stdout
dtolator --from-openapi schema.json --typescript

# Write to directory (generates dto.ts + schema.ts)
dtolator --from-openapi schema.json --zod -o ./output

# Angular services with Zod validation and promises
dtolator --from-openapi schema.json -o ./src/app/api --angular --zod --promises

# From plain JSON (like quicktype)
dtolator --from-json data.json --typescript --root MyType

# From JSON Schema
dtolator --from-json-schema schema.json --pydantic

For the complete flag reference, see docs/cli.md (generated from the CLI definition; run DTOLATOR_TEST_REFRESH=1 cargo test to regenerate).

Input types

Exactly one required:

• --from-openapi <FILE> — OpenAPI 3.x specification (richest: includes endpoints, params, validation)
• --from-json <FILE> — Plain JSON data (schema inferred automatically)
• --from-json-schema <FILE> — JSON Schema definition

Output options

• -o, --output <DIR> — Write files to directory instead of stdout
• --output-file <FILE> — Write the combined output to a single file (mutually exclusive with --output). Parent directories are created as needed. Multi-file generators (--angular, and the --zod dto.ts/schema.ts pair) require --output <DIR>; --angular --output-file is rejected.
• --delete-old — After generation, delete regular files directly in the output directory that weren't generated or skipped in this run. Subdirectories are left untouched.
• --skip-file <NAME> — Skip writing a specific file (repeatable)
• --hide-version — Omit version from generated file headers
• --debug — Verbose debug output
• --ts-enum-style <STYLE> — How named enum schemas are emitted in TypeScript/Zod output: union (default, "a" | "b"), const (as const object plus a same-named type), or enum (TypeScript enum). With Zod, the schema becomes z.enum(Name). Nullable enums and enums defined inline on a property stay unions

Angular-specific options

• --promises — Use lastValueFrom / Promise instead of Observable
• --base-url-mode <MODE> — global (default), argument, or none (relative URLs, route only)
• --api-url-variable <NAME> — Global variable name for API URL (default: API_URL)
• --ignore-operation-id — Derive method names from the operation summary, ignoring operationId

See ANGULAR.md for detailed Angular integration docs.

OpenAPI features supported

• Basic types: string, number, integer, boolean, array, object
• Enums, $ref references, nullable/optional properties
• Composition: allOf, oneOf, anyOf
• Validation: minLength, maxLength, minimum, maximum, pattern, format
• Paths: path params, query params, header params, request bodies, response types
• Map/dictionary types via additionalProperties

Incremental writes

Files are only written when content actually changes (with a fast-path file-size check), so bundler watchers won't trigger unnecessary rebuilds.

Testing

cargo test                           # Run all tests
python run-tests.py                  # Integration test suite
python run-tests.py --refresh        # Update expected outputs after intentional changes

See ADVANCED.md for endpoint generation details.

License

MIT