Config options

How configs are loaded, which formats exist and how options combine is explained in config files. This page lists every option.

Config files are named swaggerz.config.<ext>, with the extensions .ts, .mts, .cts, .js, .mjs, .cjs, .json, .yaml and .yml. JSON and YAML configs are validated against the same schema in editors (swaggerz/config.schema.json). Options marked code onlytake functions and exist only in TypeScript and JavaScript configs.

$schema

$schema

string

JSON Schema used by editors for completion and validation.

spec

specrequired

object

The specification to generate from.

spec.versionrequired

'2.0' | '3.0' | '3.1' | '3.2' | 'auto'

Specification version the input must declare: '2.0' (Swagger), '3.0', '3.1', '3.2', or 'auto' for any supported version.

spec.inputrequired

string · not empty

Path (relative to the config file) or http(s) URL of a JSON or YAML document.

spec.refs

object

External reference policy.

spec.refs.external

'none' | 'local' | 'remote' · default "local"

Which external $refs may be followed: 'none', 'local' files inside allowedDirectories, or 'remote' URLs on allowedHosts as well.

spec.refs.allowedDirectories

string[]

Directories local references may read. Defaults to the project root and the directory of the specification.

spec.refs.allowedHosts

string[]

Hosts remote references may be fetched from, e.g. 'schemas.example.com' or '*.example.com'.

spec.refs.maxDocuments

number · default 5000 · ≥ 1, integer

Maximum number of documents a description may consist of.

spec.fetch

object

Options for fetching remote documents.

spec.fetch.headers

Record<string, string>

Headers sent with remote documents (only to the origin of spec.input).

spec.fetch.timeout

number · default 30000 · ≥ 1, integer

Timeout in milliseconds.

spec.fetch.maxBytes

number · default 52428800 · ≥ 1, integer

Maximum document size in bytes.

spec.fetch.poll

boolean | number

Poll remote documents for changes in generate --watch and the dashboard: true (every 2000 ms), an interval in milliseconds, or false. By default only documents on loopback hosts (localhost, 127.0.0.1, [::1]) are polled.

spec.overlays

string[]

OpenAPI Overlay documents (1.0, 1.1 or 1.2) applied in order to the specification before it is parsed: paths relative to the config file, or http(s) URLs.

output

output

object

Where and how generated files are written.

output.directory

string · default "./src/generated/api" · not empty

Output directory, relative to the config file.

output.language

'typescript' | 'javascript' · default "typescript"

Generate TypeScript, or JavaScript with JSDoc and .d.ts declarations.

output.moduleFormat

'esm' · default "esm"

Only ES modules are generated.

output.clean

boolean · default true

Remove generated files that are no longer produced (only files recorded in the manifest).

output.declarations

boolean · default true

JavaScript output: emit .d.ts declarations next to each module.

output.importExtension

'.js' | '.ts' | 'none' · default ".js"

Extension used in relative imports between generated modules.

output.barrel

boolean · default true

Emit index barrels.

output.groupBy

'tag' | 'none' · default "tag"

Group operation modules in directories by their first tag.

output.models

'all' | 'used' · default "all"

Emit every named schema ('all') or only those operations use ('used').

output.webhooks

boolean · default true

Generate payload types and handler signatures for webhooks and callbacks.

output.banner

string

Extra text for the header comment of every generated file.

client

client

object

Defaults of the generated HTTP client.

client.adapter

'fetch' | 'axios' · default "fetch"

HTTP transport: 'fetch' (no dependencies) or 'axios'.

client.baseUrl

string

Base URL compiled into the client. Defaults to the first server of the specification.

client.operationServers

boolean · default true

Send operations that declare their own servers to that server instead of the base URL.

client.includeCredentials

boolean · default false

Send cookies with cross-origin requests.

client.headers

Record<string, string>

Static headers sent with every request.

client.timeout

number · ≥ 0, integer

Default request timeout in milliseconds (0 disables it).

client.responseStyle

'data' | 'full' · default "data"

'data' resolves with the body; 'full' resolves with { data, status, headers }.

features

features

object

Optional generators.

features.query

boolean | object · default false

Generate TanStack Query v5 hooks and option factories for React, Vue, Svelte or Solid (true: React).

features.query.framework

'react' | 'vue' | 'svelte' | 'solid' · default "react"

TanStack Query adapter: 'react' (@tanstack/react-query 5), 'vue' (@tanstack/vue-query 5), 'svelte' (@tanstack/svelte-query 6) or 'solid' (@tanstack/solid-query 5).

features.query.queryMethods

('get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace' | 'query')[] · default ["get","query"]

HTTP methods that produce query hooks; all others produce mutation hooks.

features.query.infinite

Record<string, object>

Infinite query hooks, keyed by operation name or operationId.

features.query.invalidates

Record<string, string[]>

Queries to invalidate after a successful mutation, keyed by mutation name or operationId. Values are operation names, operationIds or tags.

features.reactQuery

boolean | object · default false

Alias of query with framework 'react'. Use one or the other.

features.reactQuery.queryMethods

('get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace' | 'query')[] · default ["get","query"]

HTTP methods that produce query hooks; all others produce mutation hooks.

features.reactQuery.infinite

Record<string, object>

Infinite query hooks, keyed by operation name or operationId.

features.reactQuery.invalidates

Record<string, string[]>

Queries to invalidate after a successful mutation, keyed by mutation name or operationId. Values are operation names, operationIds or tags.

features.swr

boolean | object · default false

Generate SWR hooks (useSWR, useSWRMutation, useSWRInfinite).

features.swr.queryMethods

('get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace' | 'query')[] · default ["get","query"]

HTTP methods that produce query hooks; all others produce mutation hooks.

features.swr.infinite

Record<string, object>

Infinite query hooks, keyed by operation name or operationId.

features.swr.invalidates

Record<string, string[]>

Queries to invalidate after a successful mutation, keyed by mutation name or operationId. Values are operation names, operationIds or tags.

features.jsdoc

boolean · default true

Generate documentation comments.

features.validation

false | 'zod' | 'valibot' | 'arktype' | object · default false

Generate schemas with Zod 4, Valibot 1 or ArkType 2 and validate at runtime.

features.validation.libraryrequired

'zod' | 'valibot' | 'arktype'

Schema library: 'zod' (4), 'valibot' (1) or 'arktype' (2).

features.validation.response

boolean · default true

Validate response bodies.

features.validation.request

boolean · default false

Validate request bodies before sending.

naming

naming

object

Naming conventions.

naming.operations

'camelCase' | 'PascalCase' | 'snake_case' | 'preserve' · default "camelCase"

Operation function names.

naming.models

'camelCase' | 'PascalCase' | 'snake_case' | 'preserve' · default "PascalCase"

Model type names.

naming.files

'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case' · default "kebab-case"

File names.

naming.parameters

'preserve' | 'camelCase' · default "preserve"

Parameter property names: wire names ('preserve') or camelCase identifiers.

naming.inputSuffix

string · default "Input" · not empty

Suffix of request-side model variants created when models have readOnly or writeOnly properties.

types

types

object

How schemas map to types.

types.enums

'union' | 'const' · default "union"

'union' emits literal unions; 'const' also emits a frozen object per named enum.

types.readonlyProperties

boolean · default true

Mark readOnly properties with the readonly modifier.

types.readWrite

'split' | 'merged' · default "split"

'split' leaves readOnly properties out of request types and writeOnly properties out of response types; 'merged' uses one type for both.

types.dates

'string' | 'Date' · default "string"

Type date and date-time strings as 'string', or as 'Date' with responses converted at runtime.

dashboard

dashboard

object

Options of swaggerz dashboard.

dashboard.host

string · default "127.0.0.1" · not empty

Interface to listen on.

dashboard.port

number · default 4400 · ≥ 0, ≤ 65535, integer

Port (0 picks one).

dashboard.allowNetworkAccess

boolean · default false

Required to listen on a non-loopback interface.

dashboard.usage

object

Usage scanning of your source code.

dashboard.usage.include

string[] · default ["src"]

Files or directories to scan.

dashboard.usage.exclude

string[]

Path segments to skip.

lint

lint

object

Options of swaggerz lint.

lint.rules

Record<string, 'off' | 'info' | 'warning' | 'error'>

Severity per lint rule ('off', 'info', 'warning' or 'error'), e.g. { 'operation-id': 'error' }.

plugins

plugins

(string | [string, unknown?])[]

Plugins, run in order within their enforce group. In JSON and YAML configs, reference modules by path or package name.

hooks

hookscode only

InlineHooks

Plugin hooks given inline, without writing a plugin. They run like a plugin named config.hooks, after the default plugin group.

hooks.beforeParsecode only

function

The beforeParse hook (see the plugin hooks).

hooks.afterNormalizecode only

function

The afterNormalize hook (see the plugin hooks).

hooks.operationNamecode only

function

The operationName hook (see the plugin hooks).

hooks.modelNamecode only

function

The modelName hook (see the plugin hooks).

hooks.jsdoccode only

function

The jsdoc hook (see the plugin hooks).

hooks.queryKeycode only

function

The queryKey hook (see the plugin hooks).

hooks.resolveImportcode only

function

The resolveImport hook (see the plugin hooks).

hooks.beforeGeneratecode only

function

The beforeGenerate hook (see the plugin hooks).

hooks.generatecode only

function

The generate hook (see the plugin hooks).

hooks.transformFilecode only

function

The transformFile hook (see the plugin hooks).

hooks.afterGeneratecode only

function

The afterGenerate hook (see the plugin hooks).

hooks.beforeWritecode only

function

The beforeWrite hook (see the plugin hooks).

hooks.afterWritecode only

function

The afterWrite hook (see the plugin hooks).

Environment variables

Environment variables override the config file, and command-line flags override both. The prefix is SWAGGERZ_.

Variable	Overrides
SWAGGERZ_SPEC_INPUT	spec.input
SWAGGERZ_SPEC_VERSION	spec.version
SWAGGERZ_OUTPUT_DIRECTORY	output.directory
SWAGGERZ_OUTPUT_LANGUAGE	output.language
SWAGGERZ_CLIENT_ADAPTER	client.adapter
SWAGGERZ_CLIENT_BASE_URL	client.baseUrl