OpenAPI Codegen

OpenAPI Codegen is a set of five @spartaficial packages that read an OpenAPI 3 specification and generate the code a TypeScript project needs to talk to that API safely: the types, the Zod schemas, a validated Playwright API client and a k6 load-test client. Each generator is a command-line tool with a configuration file and a programmatic API, and all of them share one way of reading specifications, filtering operations and naming what they generate.

Version 2.0.0, release pending. The packages are being prepared for publication under the @spartaficial scope. These pages describe that release.

Which generator for which job

You want	Package	Command
TypeScript interfaces and types for every schema in the specification	@spartaficial/openapi-to-typescript	openapi-to-typescript
Zod v4 schemas that validate requests and responses at run time, with the matching types	@spartaficial/openapi-to-zod	openapi-to-zod
A Playwright API client whose every call is validated against the specification, for API tests	@spartaficial/openapi-to-zod-playwright	openapi-to-zod-playwright
A typed k6 client for load tests, with the request serialisation k6 needs	@spartaficial/openapi-to-k6	openapi-to-k6
The shared foundation: parsing, reference resolution, operation filtering and naming, for your own generator	@spartaficial/openapi-core	(library only)

Install the generator you need; the packages it builds on are installed with it:

npm install --save-dev @spartaficial/openapi-to-zod
npm install --save-dev @spartaficial/openapi-to-zod-playwright @playwright/test zod
npm install --save-dev @spartaficial/openapi-to-k6
npm install --save-dev @spartaficial/openapi-to-typescript

How the packages relate

openapi-core parses the specification, resolves $refs (across files too), filters operations and derives names. openapi-to-typescript builds on it and is in turn used by openapi-to-zod and openapi-to-k6 for the types they emit. openapi-to-zod-playwright builds on openapi-to-zod: the schemas it generates are the ones the client validates with.

openapi-core
├── openapi-to-typescript
│   ├── openapi-to-zod
│   │   └── openapi-to-zod-playwright
│   └── openapi-to-k6

Because the generators share the core, the same configuration options mean the same thing everywhere: where the specification is, which operations to include, how names are shaped, how split specifications are resolved. Each generator adds the options its output needs.

What a run looks like

Every generator works the same way:

1. npx <generator> init asks a few questions and writes a configuration file (<generator>.config.ts or .json).
2. The configuration lists one or more specifications, each with its output paths, and optional defaults shared by all of them.
3. npx <generator> reads the configuration, generates every output, and prints what it did.

Generation needs a licence key in the environment variable SPARTAFICIAL_LICENSE_KEY; building, testing and shipping the generated code never does. See licensing.md.

What is generated

• Types are plain TypeScript, one declaration per schema, with enums as enum, union or constant-object declarations as you choose.
• Zod schemas validate exactly what the specification says, in a strict, normal or loose mode, with request and response variants where readOnly and writeOnly make them differ, and z.lazy() where schemas refer to each other.
• The Playwright client has two layers: a client that sends requests as written, and a service that validates every request and response against the schemas and fails the test with a readable message when the API deviates from its specification.
• The k6 client sends typed requests with the serialisation k6 expects, and comes with a small runtime module that generated code imports; that module never needs a licence.

Generated files carry no licence logic and are yours.

Where to go next

• getting-started.md: install a generator, run init, generate from a small specification and use the output.
• concepts/configuration-files.md: how a configuration file is found and shaped, defaults and specs, executionMode, validation errors.
• concepts/specs-and-references.md: input formats, specifications split across files, refMappings for remote references, warnings.
• concepts/operation-filters.md: select which operations, and in the Playwright generator which responses, are generated.
• concepts/naming.md: how schema and operation names become identifiers, and the options that shape them.
• concepts/request-and-response-shapes.md: readOnly, writeOnly and schemaType.
• concepts/runtime-entry-points.md: the /runtime modules the k6 and Playwright output imports.
• generators/typescript.md: the TypeScript types generator.
• generators/zod.md: the Zod schemas generator.
• generators/zod-playwright.md: the validated Playwright API client.
• generators/k6.md: the typed k6 client.
• reference/cli.md: every command and flag of the four CLIs.
• licensing.md: setting the licence key, what it covers, what works without one, and the error codes.
• troubleshooting.md: the errors and warnings you may meet, and what to do about each.