openapi-to-zod-playwright options

Every configuration option of @spartaficial/openapi-to-zod-playwright: its type, its default and where it may be set. This page is generated from the generator's configuration schema, so it cannot drift from the code. For how the options combine, read the Playwright generator guide; for where the options go, read Configuration files; for what the other generators accept, read Option parity.

Spec entry options

Each entry in specs accepts these options. The 3 required options come first, then the rest alphabetically. The "In defaults" column says whether the option may also be set once, under defaults, for every entry.

Option	Type	Default	In defaults	Description
input	string	required	no	Input OpenAPI specification file path (YAML or JSON)
outputClient	string	required	no	Output file path for client class
outputTypes	string	required	no	Output file path for the generated schemas and types, or for the types alone when outputZodSchemas is set
basePath	string	—	yes	Base path to prepend to all API endpoints
batchSize	number > 0	10	yes	Batch size for parallel execution
cacheSize	number > 0	1000	yes	Cache size for pattern regex compilation
customDateTimeFormatRegex	string | RegExp	—	yes	Custom regex pattern for date-time format validation
defaultNullable	boolean	false	yes	Treat all properties as nullable by default when not explicitly specified
emptyObjectBehavior	"strict" | "loose" | "record"	"loose"	yes	Behavior for empty object schemas (objects with no properties defined)
enumFormat	"union" | "const-object"	"const-object"	yes	Format for generating enums in TypeScript types (when using outputZodSchemas)
fallbackContentTypeParsing	"text" | "json" | "body"	"text"	yes	Fallback parsing method for unknown or missing content types in service generation
fileHeader	string[]	—	yes	Custom comment lines to add at the very top of generated files
ignoreHeaders	string[]	—	yes	Header parameters to ignore during schema and service generation
includeDescriptions	boolean	true	yes	Include JSDoc comments from schema descriptions
mode	"strict" | "normal" | "loose"	"strict"	yes	Object validation mode
name	string	—	no	A label for this specification entry
operationFilters	object	—	yes	Operation filtering options (Playwright-specific with status code support) (see the table below)
output	string	—	no	Deprecated. Former name of outputTypes, accepted for backward compatibility
outputService	string	—	no	Output file path for the service class
outputZodSchemas	string	—	no	Output path for Zod schemas when using separate type/schema files
preferredContentTypes	string[]	["application/json"]	yes	Preferred content types for response handling, in order of priority
prefix	string	—	yes	Prefix to add to all generated type/schema names
refMappings	Record<string, string>	—	yes	Redirect remote $ref documents to local files, keyed by URL prefix
request	object	—	yes	Request-specific options that override the top-level options (see the table below)
response	object	—	yes	Response-specific options that override the top-level options (see the table below)
showStats	boolean	true	yes	Show generation statistics in output file
showWarnings	boolean	true	yes	Enable or disable warning messages during generation
stripPathPrefix	string	—	yes	Strip a common prefix from all paths before processing
stripSchemaPrefix	string | string[]	—	yes	Strip a common prefix from all schema names before processing
suffix	string	—	yes	Suffix to add to generated type/schema names
typeAssertionThreshold	integer >= 0	0	yes	Complexity threshold for switching to the double assertion (as unknown as) in generated schema declarations (only applies when outputZodSchemas is used)
useDescribe	boolean	false	yes	Whether to add .describe() calls for better error messages
useOperationId	boolean	false	yes	Whether to use operationId from OpenAPI spec for method names
uuidFormat	"uuid" | "guid" | "uuidv1" | "uuidv2" | "uuidv3" | "uuidv4" | "uuidv5" | "uuidv6" | "uuidv7" | "uuidv8"	"uuid"	yes	UUID/GUID format for Zod validation
validateServiceRequest	boolean	false	yes	Whether to validate request body data with Zod schemas in service methods
zodErrorFormat	"standard" | "prettify" | "prettifyWithValues"	"prettifyWithValues"	yes	Zod error formatting style for validation errors in service methods

operationFilters

Options of the operationFilters object. This generator adds includeStatusCodes and excludeStatusCodes to the operation filters every generator shares.

Option	Type	Default	Description
excludeDeprecated	boolean	false	Exclude operations marked as deprecated
excludeMethods	string[]	—	Exclude operations with one of these HTTP methods
excludeOperationIds	string[]	—	Exclude operations whose operationId matches one of these patterns
excludePaths	string[]	—	Exclude operations whose path matches one of these patterns
excludeStatusCodes	string[]	—	Exclude these status codes from generated response types
excludeTags	string[]	—	Exclude operations that carry any of these tags
includeMethods	string[]	—	Include only operations with one of these HTTP methods
includeOperationIds	string[]	—	Include only operations whose operationId matches one of these patterns
includePaths	string[]	—	Include only operations whose path matches one of these patterns
includeStatusCodes	string[]	—	Include only these status codes in generated response types
includeTags	string[]	—	Include only operations that carry at least one of these tags

request and response

The request and response objects accept the same options, each applying to its own side of the exchange.

Option	Type	Default	Description
defaultNullable	boolean	the top-level defaultNullable	Accepted for symmetry with the top-level option, but not applied: the top-level defaultNullable governs both contexts
emptyObjectBehavior	"strict" | "loose" | "record"	the top-level emptyObjectBehavior	Accepted for symmetry with the top-level option, but not applied: the top-level emptyObjectBehavior governs both contexts
includeDescriptions	boolean	the top-level includeDescriptions	Whether to include descriptions as JSDoc comments
mode	"strict" | "normal" | "loose"	the top-level mode	Object validation mode
useDescribe	boolean	the top-level useDescribe	Whether to add .describe() calls for better error messages

Config file

The generator reads openapi-to-zod-playwright.config.ts, openapi-to-zod-playwright.config.json or an "openapi-to-zod-playwright" key in package.json. Whatever the format, the file has this shape:

import { defineConfig } from "@spartaficial/openapi-to-zod-playwright";

export default defineConfig({
	// Optional. Any of the 29 options marked "yes" above, applied to every entry in specs
	defaults: {},
	// Required. One entry per specification; an entry's own options override defaults
	specs: [{ input: "openapi.yaml", outputClient: "tests/client.ts", outputTypes: "tests/schemas.ts" }],
	// Optional. How several entries are processed: "parallel" or "sequential"; default "sequential"
	executionMode: "sequential",
});

defaults takes the options marked "yes" in the "In defaults" column; paths and name are always per entry. executionMode only matters when specs has more than one entry.