Roadmap

Status of the initial implementation

The first version was built in nine phases. Each phase ends with tests that compile and, where relevant, execute the generated code.

Phase	Scope	Status
1	Project setup, configuration (defineConfig, loading, validation, environment overrides), diagnostics, CLI skeleton	Done
2	Loader (JSON/YAML, remote documents, limits), reference resolution with a security policy, version detection, Swagger 2.0 / OpenAPI 3.0 / 3.1 adapters, the IR	Done
3	Analysis (dependency graph, naming, module layout) and code generation: models, operations, client, runtime with fetch and axios transports, TypeScript and JavaScript	Done
4	Output: manifest, ownership rules, atomic writes, cleanup, diffs; generate --watch, validate, inspect, clean, doctor	Done
5	TanStack Query v5 hooks, query options, keys, infinite queries, mutations with invalidation; Zod schemas and validation	Done
6	Plugins and hooks	Done
7	Dashboard: overview, operations, models, dependencies, usage scanning, generation preview	Done
8	Tree-shaking and compatibility verification, benchmarks, documentation, examples, CI and release automation	Done
9	Former limitations: read/write model split, Date conversion, multiple request media types, declared 3xx responses, per-operation servers, webhooks and callbacks, not/conditional/dependent assertions in Zod, relative $id scopes; JSON and YAML configs, plugin references; oxc-based usage scanning; dashboard redesign; oxlint/oxfmt; release-it	Done

What “done” is backed by: the unit and integration suites, pnpm compat (TypeScript 5.0/6/7 and the oldest supported release of every optional dependency, with the latest versions in the integration tests), pnpm test:smoke on Node.js 18–24, pnpm test:pack and scripts/verify-examples.ts. See compatibility for exactly what is and is not verified.

Before the first release

• Create the alirezahematidev/swaggerz repository, register the swaggerz name on npm and configure trusted publishing and the npm environment (CONTRIBUTING.md). The unscoped name was available on 2026-10-19; nothing has been published.
• Run the CI workflow on all platforms. Windows and Linux are covered by the CI matrix but have not yet been exercised; development happened on macOS.

After the initial implementation

Implemented after the first version, with tests and documentation:

Item	Where it is documented
generate --check for CI	generated code
Errors typed by status	generated code, decision 15
retry() and refreshAuth() middleware	generated code
Live reload for remote specifications	configuration (spec.fetch.poll), dashboard
OpenAPI 3.2	compatibility, generated code, decision 16
MCP server for coding agents	MCP server, decision 20
TanStack Query for Vue, Svelte and Solid; SWR	data fetching, decision 18
OpenAPI Overlays	overlays, decision 19
Valibot and ArkType validation	generated code, decision 17
swaggerz lint	linting, decision 21
Docs website	website/
sz alias of the CLI	README

Candidates for later versions

Ordered roughly by expected value. None of them is committed.

• Typed streaming responses (server-sent events, JSON Lines) for OpenAPI 3.2 itemSchema and x- annotations in 3.0/3.1 (today such content is read as text).
• Opt-in int64 → bigint (needs a JSON parser that keeps large integers exact, since JSON.parse already loses precision before any conversion).
• XML request and response serialization (today XML bodies are passed and returned as strings).
• $dynamicRef / $recursiveRef.
• Incremental compilation in watch mode (today the whole specification is recompiled; only changed files are written).
• A stable, documented IR (currently experimental, see plugins).

Known limitations of the current version are listed in the README.