04Reference
generate(), validate(), loadConfig(), defineConfig() and their types, read from the published declarations.
The CLI is a thin layer over these functions. Use them to generate from a build script, a test or another tool:
import { formatDiagnostic, generate } from 'swaggerz';
// Loads swaggerz.config.* from the working directory, like the CLI.const result = await generate({ cwd: '.' });for (const diagnostic of result.diagnostics) console.log(formatDiagnostic(diagnostic));if (!result.ok) throw new Error('Generation failed; nothing was written.');console.log(`${result.write?.created.length ?? 0} files created`);Everything below is exported from swaggerz and follows semantic versioning, except the types of the intermediate representation and the project model, which areexperimental until 1.0 and may change in minor releases.
defineConfigDeclares a configuration with full type checking and editor autocomplete.
function defineConfig(config: UserConfig): UserConfig;function defineConfig(config: (env: ConfigEnv) => UserConfig | Promise<UserConfig>): (env: ConfigEnv) => UserConfig | Promise<UserConfig>;import { defineConfig } from 'swaggerz';
export default defineConfig({ spec: { version: '3.1', input: './openapi.yaml' }, output: { directory: './src/generated/api' },});definePluginDeclares a plugin with full type checking.
function definePlugin(plugin: SwaggerzPlugin): SwaggerzPlugin;formatDiagnosticFormats a diagnostic for terminals: severity, code, message, location, context and hint. Control characters in the diagnostic's text are escaped (see printable).
function formatDiagnostic(diagnostic: Diagnostic, options?: FormatOptions): string;generateLoads configuration, compiles the specification and writes the generated client. Throws SwaggerzError when the configuration cannot be loaded; all other problems are returned as diagnostics with ok: false.
function generate(options?: GenerateOptions): Promise<GenerationResult>;loadConfigLoads, merges, validates and resolves configuration. Throws SwaggerzError on failure.
function loadConfig(options: LoadConfigOptions): Promise<LoadedConfig>;validateValidates the configuration and specification and generates in memory without writing.
function validate(options?: ApiOptions): Promise<CompileResult>;SwaggerzErrorThrown when compilation cannot continue. Carries the diagnostics collected so far.
class SwaggerzError extends Error { readonly diagnostics: readonly Diagnostic[]; constructor(message: string, diagnostics?: readonly Diagnostic[]);}interface ApiOptions { /** Directory used to find the config file. Defaults to `process.cwd()`. */ readonly cwd?: string; /** Explicit config file path. */ readonly configFile?: string; /** Use this configuration instead of loading a config file. */ readonly config?: UserConfig; /** Deep overrides applied on top of the loaded configuration. */ readonly overrides?: Record<string, unknown>;}interface BeforeParseContext extends PluginContext { /** URL or absolute path of the root document. */ readonly source: string;}interface ClientConfig { /** HTTP transport used by generated operations. Default `'fetch'`. */ adapter?: 'fetch' | 'axios'; /** * Base URL compiled into the generated client. Defaults to the first server declared by the * specification. Can be changed at runtime with `client.setConfig({ baseUrl })`. */ baseUrl?: string; /** * Send operations that declare their own `servers` (on the operation or its path) to the first * of those servers instead of the base URL. Default `true`; can be changed at runtime. */ operationServers?: boolean; /** Send cookies on cross-origin requests (`credentials: 'include'` / `withCredentials`). */ includeCredentials?: boolean; /** Static headers compiled into the generated client. */ headers?: Record<string, string>; /** Default request timeout in milliseconds. */ timeout?: number; /** * `'data'` (default): operations resolve with the parsed response body. * `'full'`: operations resolve with `{ data, status, headers }` discriminated by status. */ responseStyle?: 'data' | 'full';}interface CompileResult { /** True when no error diagnostics were reported. */ readonly ok: boolean; readonly ir?: ApiDocument; readonly project?: ProjectModel; /** Generated files sorted by path (empty when compilation failed). */ readonly files: readonly GeneratedFile[]; readonly diagnostics: readonly Diagnostic[]; readonly store?: DocumentStore; readonly runner: PluginRunner; /** Milliseconds per pipeline stage. */ readonly timings: Readonly<Record<string, number>>;}interface ConfigEnv { /** CLI command being executed, e.g. `generate` or `dashboard`. */ readonly command: string;}interface DashboardConfig { /** Default `127.0.0.1`. Binding to a non-loopback address requires `allowNetworkAccess`. */ host?: string; /** Default `4400`. `0` selects a free port. */ port?: number; /** Required to bind the dashboard to a non-loopback interface. Default `false`. */ allowNetworkAccess?: boolean; usage?: UsageScanConfig;}interface DataFetchingConfig { /** * HTTP methods that produce query hooks; others produce mutation hooks. Default * `['get', 'query']` (`query` is OpenAPI 3.2's safe method with a body). */ queryMethods?: StandardHttpMethod[]; /** * Infinite query hooks, keyed by operation name (after naming conventions) or `operationId`. * `pageParam` names the query parameter that receives the page parameter. */ infinite?: Record<string, { pageParam: string; }>; /** * Query invalidation after successful mutations, keyed by mutation operation name or * `operationId`. Values are operation names/ids of queries or tag names. */ invalidates?: Record<string, string[]>;}interface Diagnostic { readonly code: string; readonly severity: Severity; readonly message: string; readonly location?: SourceLocation; /** Operation context such as `GET /pets/{id} (getPet)`. */ readonly operation?: string; /** Actionable advice for resolving the problem. */ readonly hint?: string; /** Name of the plugin that reported or caused the diagnostic. */ readonly plugin?: string;}interface FeaturesConfig { /** * Generate TanStack Query v5 hooks and option factories for a framework. `true` generates * React hooks. Default `false`. */ query?: boolean | QueryConfig; /** Alias of `query` with `framework: 'react'`. Use one or the other. */ reactQuery?: boolean | ReactQueryConfig; /** Generate SWR hooks (`useSWR`, `useSWRMutation`, `useSWRInfinite`). Default `false`. */ swr?: boolean | SwrConfig; /** Generate JSDoc for every exported symbol. Default `true`. */ jsdoc?: boolean; /** * Generate schemas with Zod 4, Valibot 1 or ArkType 2, and validate at runtime. Default * `false`. */ validation?: false | ValidationLibrary | ({ library: ValidationLibrary; } & ValidationOptions);}interface FetchConfig { /** Extra headers for remote documents, e.g. an authorization header for a private spec. */ headers?: Record<string, string>; /** Timeout per request in milliseconds. Default `30000`. */ timeout?: number; /** Maximum document size in bytes. Default `52428800` (50 MiB). */ maxBytes?: number; /** * Poll remote documents for changes in `generate --watch` and the dashboard, with conditional * requests. `true` polls every 2000 ms, a number sets the interval in milliseconds (at least * 500), `false` turns polling off. Default: only documents on loopback hosts (`localhost`, * `127.0.0.1`, `[::1]`), such as a specification served by a local backend, every 2000 ms. */ poll?: boolean | number;}interface FileChange { /** Path relative to the output directory. */ readonly path: string; readonly kind: FileChangeKind; /** Previous content (for updates and deletes of text files). */ readonly before?: string; /** New content (for creates and updates). */ readonly after?: string;}interface FileContext extends GenerateContext { /** Files produced so far, in deterministic order. */ readonly files: readonly GeneratedFile[];}interface GenerateContext extends PluginContext { /** IR plus resolved names and layout. Experimental. */ readonly project: ProjectModel;}interface GeneratedExport { readonly name: string; readonly kind: GeneratedExportKind; /** True for type-only exports. */ readonly typeOnly: boolean;}interface GeneratedFile { /** Path relative to the output directory, always using `/` separators. */ readonly path: string; readonly content: string; /** Producer, e.g. `core:operation`, `core:model` or `plugin:<name>`. */ readonly origin: string; /** Exported symbols, used by the barrel, the dashboard and usage scanning. */ readonly exports?: readonly GeneratedExport[]; /** IR entities this file was produced from. */ readonly sources?: { readonly operations?: readonly string[]; readonly schemas?: readonly string[]; };}interface GenerateOptions extends ApiOptions { /** Compute changes without writing files. */ readonly dryRun?: boolean; /** Overwrite user-owned or hand-edited files. */ readonly force?: boolean;}interface GenerationResult extends Omit<CompileResult, 'ok' | 'diagnostics'> { readonly ok: boolean; readonly diagnostics: readonly Diagnostic[]; readonly plan?: WritePlan; readonly write?: WriteResult; /** * How the output manifest's file list changes (or would change in a dry run). The generator * version recorded in the manifest is not compared. */ readonly manifestChange?: 'create' | 'update' | 'unchanged';}interface JsDocBlock { /** First paragraph. */ readonly summary?: string; /** Additional paragraphs. */ readonly description?: string; readonly tags: readonly JsDocTag[];}interface JsDocTag { /** Tag name without `@`, e.g. `param`, `returns`, `deprecated`. */ readonly tag: string; /** Raw tag text (escaped during rendering). */ readonly text?: string;}interface LintConfig { /** * Severity per rule, e.g. `{ 'operation-id': 'error', 'inline-schema': 'off' }`. Rules not * listed keep their default severity (see the diagnostics reference). */ rules?: Record<string, LintSeverity>;}interface LoadConfigOptions { /** Working directory used to search for a config file. */ readonly cwd: string; /** Explicit config file path (absolute or relative to `cwd`). */ readonly configFile?: string; /** Use this config object instead of loading a file. */ readonly inlineConfig?: UserConfig; /** CLI command name, passed to config functions. */ readonly command?: string; /** Deep overrides applied after environment variables (e.g. from CLI flags). */ readonly overrides?: Record<string, unknown>; readonly env?: NodeJS.ProcessEnv;}interface LoadedConfig { readonly config: ResolvedConfig; readonly plugins: readonly SwaggerzPlugin[]; /** Absolute path of the config file, when one was loaded. */ readonly file?: string; /** Environment variables that changed the configuration. */ readonly envApplied: readonly string[]; /** * Absolute paths of the local files, besides the config file, that the configuration was loaded * from: plugin modules referenced by a relative or absolute path or a `file:` URL (sorted). * Watch them to reload when a plugin changes; loading the configuration again picks up their * changes. Modules that these files or the config file import themselves are not listed, and * Node.js caches them for the life of the process. */ readonly watchFiles: readonly string[];}interface NamingConfig { /** Operation function names. Default `'camelCase'`. */ operations?: 'camelCase' | 'PascalCase' | 'snake_case' | 'preserve'; /** Model type names. Default `'PascalCase'`. */ models?: 'PascalCase' | 'camelCase' | 'snake_case' | 'preserve'; /** File names. Default `'kebab-case'`. */ files?: 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case'; /** * Property names of generated parameter objects. `'preserve'` (default) keeps wire names * (quoted when necessary); `'camelCase'` converts them to identifiers. */ parameters?: 'preserve' | 'camelCase'; /** * Suffix of the request-side variant of models that contain `readOnly` or `writeOnly` * properties (see `types.readWrite`). Default `'Input'`, e.g. `PetInput`. */ inputSuffix?: string;}interface OutputConfig { /** Output directory, relative to the config file. Default `./src/generated/api`. */ directory?: string; /** Default `'typescript'`. */ language?: 'typescript' | 'javascript'; /** Only ES modules are generated. Reserved for future formats. */ moduleFormat?: 'esm'; /** * Remove generated files that are no longer produced. Only files recorded in the output * manifest are ever removed. Default `true`. */ clean?: boolean; /** JavaScript output only: emit `.d.ts` declarations next to each module. Default `true`. */ declarations?: boolean; /** * Extension used in relative import specifiers. `'.js'` (default) works with Node ESM, * TypeScript `nodenext`/`bundler` resolution and all major bundlers. */ importExtension?: '.js' | '.ts' | 'none'; /** Emit an `index` barrel re-exporting operations, models and the client. Default `true`. */ barrel?: boolean; /** Directory grouping for operation modules. Default `'tag'` (first tag). */ groupBy?: 'tag' | 'none'; /** Emit every named schema (`'all'`, default) or only schemas reachable from operations. */ models?: 'all' | 'used'; /** * Generate payload types and handler signatures for webhooks (OpenAPI 3.1) and callbacks * (OpenAPI 3.x). Default `true`. */ webhooks?: boolean; /** Extra text placed in the header comment of every generated file. */ banner?: string;}interface PluginContext { readonly config: ResolvedConfig; /** Report a diagnostic. Error diagnostics abort generation before files are written. */ report(diagnostic: Omit<Diagnostic, 'plugin'>): void;}interface QueryConfig extends DataFetchingConfig { /** * TanStack Query adapter: `'react'` (`@tanstack/react-query` 5), `'vue'` * (`@tanstack/vue-query` 5), `'svelte'` (`@tanstack/svelte-query` 6, Svelte 5) or `'solid'` * (`@tanstack/solid-query` 5). Default `'react'`. */ framework?: QueryFramework;}interface RefsConfig { /** * Which external references may be followed. * - `'none'`: only references inside the root document. * - `'local'` (default): local files inside `allowedDirectories`. Remote documents may still * reference same-origin URLs. * - `'remote'`: local files plus `http(s)` URLs whose host is listed in `allowedHosts`. */ external?: 'none' | 'local' | 'remote'; /** * Directories that local references may read from. Defaults to the project root and the * directory of the root specification. */ allowedDirectories?: string[]; /** Hosts remote references may be fetched from, e.g. `['schemas.example.com']`. */ allowedHosts?: string[]; /** Maximum number of documents a description may consist of. Default `5000`. */ maxDocuments?: number;}interface ResolvedConfig { /** Directory the config file lives in (or the working directory without a config file). */ readonly root: string; /** Absolute path of the loaded config file, if any. */ readonly configFile?: string; readonly spec: { readonly version: '2.0' | '3.0' | '3.1' | '3.2' | 'auto'; /** Absolute path or URL. */ readonly input: string; readonly refs: { readonly external: 'none' | 'local' | 'remote'; readonly allowedDirectories: readonly string[]; readonly allowedHosts: readonly string[]; readonly maxDocuments: number; }; readonly fetch: { readonly headers: Readonly<Record<string, string>>; readonly timeout: number; readonly maxBytes: number; /** Which remote documents are polled for changes while watching, and how often (ms). */ readonly poll: { readonly hosts: 'loopback' | 'all' | 'none'; readonly interval: number; }; }; /** Overlay documents applied in order: absolute paths or URLs. */ readonly overlays: readonly string[]; }; readonly output: { /** Absolute path. */ readonly directory: string; readonly language: 'typescript' | 'javascript'; readonly moduleFormat: 'esm'; readonly clean: boolean; readonly declarations: boolean; readonly importExtension: '.js' | '.ts' | 'none'; readonly barrel: boolean; readonly groupBy: 'tag' | 'none'; readonly models: 'all' | 'used'; readonly webhooks: boolean; readonly banner?: string; }; readonly client: { readonly adapter: 'fetch' | 'axios'; readonly baseUrl?: string; readonly operationServers: boolean; readonly includeCredentials: boolean; readonly headers: Readonly<Record<string, string>>; readonly timeout?: number; readonly responseStyle: 'data' | 'full'; }; readonly features: { readonly jsdoc: boolean; /** TanStack Query hooks (`features.query` or its alias `features.reactQuery`). */ readonly query: false | (ResolvedDataFetching & { readonly framework: QueryFramework; }); readonly swr: false | ResolvedDataFetching; readonly validation: false | { readonly library: ValidationLibrary; readonly response: boolean; readonly request: boolean; }; }; readonly naming: { readonly operations: 'camelCase' | 'PascalCase' | 'snake_case' | 'preserve'; readonly models: 'PascalCase' | 'camelCase' | 'snake_case' | 'preserve'; readonly files: 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case'; readonly parameters: 'preserve' | 'camelCase'; readonly inputSuffix: string; }; readonly types: { readonly enums: 'union' | 'const'; readonly readonlyProperties: boolean; readonly readWrite: 'split' | 'merged'; readonly dates: 'string' | 'Date'; }; readonly dashboard: { readonly host: string; readonly port: number; readonly allowNetworkAccess: boolean; readonly usage: { readonly include: readonly string[]; readonly exclude: readonly string[]; }; }; readonly lint: { /** Severities configured per rule; rules not listed keep their defaults. */ readonly rules: Readonly<Record<string, LintSeverity>>; };}interface SourceLocation { /** Absolute file path or URL of the document. */ readonly file: string; /** RFC 6901 JSON pointer inside the document, e.g. `/paths/~1pets/get`. */ readonly pointer?: string; /** 1-based line, resolved lazily when available. */ readonly line?: number; /** 1-based column, resolved lazily when available. */ readonly column?: number;}interface SpecConfig { /** * Specification family the input must conform to. A document declaring a different version is * rejected instead of being reinterpreted. Use `'auto'` to accept any supported version. */ version: SpecVersionOption; /** Local path (relative to the config file) or `http(s)://` URL of a JSON or YAML document. */ input: string; /** External `$ref` resolution policy. */ refs?: RefsConfig; /** Options for fetching remote documents. */ fetch?: FetchConfig; /** * OpenAPI Overlay documents (1.0, 1.1 or 1.2) applied in order to the root document before it * is parsed: local paths relative to the config file, or `http(s)://` URLs. Use them to fix a * third-party specification (a missing `operationId`, a wrong type, an internal endpoint to * hide) without forking it. */ overlays?: string[];}interface SwaggerzPlugin { /** Unique, human-readable plugin name used in diagnostics. */ readonly name: string; readonly enforce?: 'pre' | 'post'; /** * Before the document is validated and parsed. Receives the raw root document and may return a * replacement (for example to patch a broken specification). */ beforeParse?(document: unknown, ctx: BeforeParseContext): MaybePromise<unknown>; /** After the document is normalized into the IR. May return a modified IR. */ afterNormalize?(ir: ApiDocument, ctx: AfterNormalizeContext): MaybePromise<ApiDocument | void>; /** Override an operation function name. Return `undefined` to keep the suggestion. */ operationName?(operation: OperationIR, suggested: string): string | undefined; /** Override a model type name. Return `undefined` to keep the suggestion. */ modelName?(definition: SchemaDefinition, suggested: string): string | undefined; /** Customize a JSDoc block before rendering. */ jsdoc?(block: JsDocBlock, target: JsDocTarget): JsDocBlock | void; /** * Customize the static prefix of a query key (TanStack Query or SWR hooks). The request * parameters are always appended as the final element. */ queryKey?(operation: OperationIR, prefix: readonly string[]): readonly string[] | void; /** Customize a relative import specifier between two generated modules. */ resolveImport?(request: { readonly from: string; readonly to: string; readonly specifier: string; }): string | void; /** After semantic analysis, before any code is generated. */ beforeGenerate?(ctx: GenerateContext): MaybePromise<void>; /** Add files. Runs after the built-in generators. */ generate?(ctx: FileContext): MaybePromise<readonly GeneratedFile[] | void>; /** Modify a file (return the new file), drop it (`null`) or keep it (`undefined`). */ transformFile?(file: GeneratedFile, ctx: FileContext): MaybePromise<GeneratedFile | null | void>; /** After all files are generated and transformed. */ afterGenerate?(files: readonly GeneratedFile[], ctx: GenerateContext): MaybePromise<void>; /** Before files are written (also runs in dry-run mode). Throw to abort. */ beforeWrite?(plan: WritePlan, ctx: GenerateContext): MaybePromise<void>; /** After output was written successfully. Not called in dry-run mode. */ afterWrite?(result: WriteResult, ctx: GenerateContext): MaybePromise<void>;}interface TypesConfig { /** * `'union'` (default): enums become string/number literal unions (no runtime code). * `'const'`: additionally emit a frozen `as const` object per named enum. */ enums?: 'union' | 'const'; /** Mark `readOnly` properties with the `readonly` modifier. Default `true`. */ readonlyProperties?: boolean; /** * `'split'` (default): `readOnly` properties are left out of request types and `writeOnly` * properties out of response types; models that differ get a request-side variant * (`PetInput`). `'merged'`: one type per model, used for both directions. */ readWrite?: 'split' | 'merged'; /** * `'string'` (default): `format: date` and `date-time` values are strings. * `'Date'`: they are typed as `Date`; response bodies are converted at runtime and `Date` * values in requests are serialized (`date` as `YYYY-MM-DD`, `date-time` as ISO 8601). */ dates?: 'string' | 'Date';}interface UsageScanConfig { /** Directories or files scanned for generated API usage. Default `['src']`. */ include?: string[]; /** Path segments to skip. `node_modules` and the output directory are always skipped. */ exclude?: string[];}interface UserConfig { spec: SpecConfig; output?: OutputConfig; client?: ClientConfig; features?: FeaturesConfig; naming?: NamingConfig; types?: TypesConfig; dashboard?: DashboardConfig; /** Options of `swaggerz lint`. */ lint?: LintConfig; /** Plugins run in array order within their `enforce` group (`pre`, default, `post`). */ plugins?: PluginEntry[]; /** Inline lifecycle hooks, run after all plugins of the default group. */ hooks?: InlineHooks;}interface ValidationOptions { /** Validate response bodies in generated operations. Default `true`. */ response?: boolean; /** Validate request bodies before sending. Default `false`. */ request?: boolean;}interface WritePlan { /** Absolute output directory. */ readonly directory: string; /** Sorted by path. */ readonly changes: readonly FileChange[];}interface WriteResult { readonly directory: string; readonly created: readonly string[]; readonly updated: readonly string[]; readonly deleted: readonly string[]; readonly unchanged: readonly string[]; readonly dryRun: boolean;}type AfterNormalizeContext = PluginContext;type CaseStyle = 'camelCase' | 'PascalCase' | 'snake_case' | 'kebab-case' | 'preserve';type ConfigExport = UserConfig | ((env: ConfigEnv) => UserConfig | Promise<UserConfig>);type FileChangeKind = 'create' | 'update' | 'delete' | 'unchanged';type GeneratedExportKind = 'operation'/** `is<Operation>ApiError`: narrows an error to the operation's `ApiError`s. */ | 'error-guard' | 'type' | 'model' | 'hook' | 'query-options' | 'query-key' | 'mutation-options' | 'schema' | 'client' | 'runtime';type InlineHooks = Omit<SwaggerzPlugin, 'name' | 'enforce'>;type JsDocTarget = { readonly kind: 'operation'; readonly operation: OperationIR;} | { readonly kind: 'model'; readonly definition: SchemaDefinition;} | { readonly kind: 'hook'; readonly operation: OperationIR;};type LintSeverity = 'off' | 'info' | 'warning' | 'error';type QueryFramework = 'react' | 'vue' | 'svelte' | 'solid';type ReactQueryConfig = DataFetchingConfig;type Severity = 'error' | 'warning' | 'info';type SpecVersionOption = '2.0' | '3.0' | '3.1' | '3.2' | 'auto';type SwrConfig = DataFetchingConfig;type ValidationLibrary = 'zod' | 'valibot' | 'arktype';Plugins receive these in their hook contexts. They are listed here so plugin authors can find them; their shapes are in dist/ir/types.d.ts anddist/analysis/types.d.ts of the package.
isStandardMethodwireMethodHTTP_METHODSIR_VERSIONApiDocumentApiInfoArrayConstraintsArraySchemaBinarySchemaBooleanSchemaDiscriminatorIREncodingIREnumSchemaExampleIRExternalDocsIRHeaderIRIntersectionSchemaMediaTypeIRModelSymbolNeverSchemaNullSchemaNumberConstraintsNumberSchemaOAuthFlowIROAuthFlowsIRObjectConstraintsObjectSchemaOperationIROperationSymbolParameterIRProjectModelPropertyIRRefSchemaRequestBodyIRResponseIRSchemaAssertionsSchemaDefinitionSchemaMetaServerIRSourceRefStringConstraintsStringSchemaTagIRUnionSchemaUnknownSchemaWebhookIRExtensionsHttpMethodJsonPrimitiveJsonValueParameterLocationParameterStyleSchemaIRSchemaKindSecurityRequirementIRSecuritySchemeIRSpecVersionStandardHttpMethod