Parser Configuration

The parser option customizes how your OpenAPI specification is parsed and transformed before plugins process it.

Overview

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: './src/client',
  parser: {
    filters: {
      tags: {
        include: ['users', 'posts'],
      },
    },
    transforms: {
      enums: 'root',
    },
  },
});

Filters

Filters select a subset of your OpenAPI specification before it’s passed to plugins.

object

Filter operations (endpoints) to include or exclude.

Show Operations Filter

string[]

Process only operations matching these patterns.

filters: {
  operations: {
    include: ['GET /api/v1/users', 'POST /api/v1/users'],
  },
}

string[]

Exclude operations matching these patterns.In case of conflicts, exclude takes precedence over include.

filters: {
  operations: {
    exclude: ['DELETE /api/v1/admin/*'],
  },
}

object

Filter by OpenAPI tags.

Show Tags Filter

string[]

Process only resources with these tags.

filters: {
  tags: {
    include: ['users', 'posts'],
  },
}

string[]

Exclude resources with these tags.

filters: {
  tags: {
    exclude: ['internal', 'deprecated'],
  },
}

object

Filter schema definitions to include or exclude.

Show Schemas Filter

string[]

Process only these schema definitions.

string[]

Exclude these schema definitions.

object

Filter parameter definitions.

Show Parameters Filter

string[]

Process only these parameters.

string[]

Exclude these parameters.

object

Filter request body definitions.

Show Request Bodies Filter

string[]

Process only these request bodies.

string[]

Exclude these request bodies.

object

Filter response definitions.

Show Responses Filter

string[]

Process only these responses.

string[]

Exclude these responses.

boolean

default:true

Include deprecated resources in the output.Set to false to exclude all resources marked as deprecated in your OpenAPI specification.

parser: {
  filters: {
    deprecated: false,
  },
}

boolean

default:false

Keep reusable components without any references from operations in the output.By default, unreferenced schemas are excluded.

boolean

default:false

Preserve key order when processing your input. Disabled by default for performance.

Transforms

Transforms modify or normalize the OpenAPI specification in standardized ways.

boolean | string | object

default:false

Control how enums are handled in your specification.Your input might contain two types of enums:

Root enums: Defined as reusable components
Inline enums: Nested within other schemas

Only root enums are typically exported by plugins. Use this transform to promote inline enums to root level.

Show Enums Transform Configuration

boolean

default:true

Whether this transform is enabled.

string

default:"root"

Controls enum handling:

'root' — Promote inline enums to reusable root components
'inline' — Keep all enums inline within schemas

string

default:"PascalCase"

Casing convention for generated enum names.Options: 'camelCase', 'PascalCase', 'snake_case', 'SCREAMING_SNAKE_CASE', 'preserve'

string | function

default:"{{name}}Enum"

Customize the generated enum name. Use {{name}} placeholder or provide a function.

parser: {
  transforms: {
    enums: true, // Enable with defaults (mode: 'root')
  },
}

parser: {
  transforms: {
    enums: 'root', // Promote inline enums to root
  },
}

parser: {
  transforms: {
    enums: {
      enabled: true,
      mode: 'root',
      case: 'PascalCase',
      name: '{{name}}Enum',
    },
  },
}

boolean | object

default:true

Separate schemas for read (response) and write (request) operations.Schemas might contain read-only or write-only fields. This transform creates separate schemas to avoid asking users to provide read-only fields in requests or expecting write-only fields in responses.

Show Read/Write Transform Configuration

boolean

default:true

Whether this transform is enabled.

string | object

default:"{{name}}Writable"

Configuration for request-specific schemas (containing write-only fields).

string

default:"preserve"

Casing convention for generated names.

string | function

default:"{{name}}Writable"

Naming pattern for request schemas.

string | object

default:"{{name}}"

Configuration for response-specific schemas (containing read-only fields).

string

default:"preserve"

Casing convention for generated names.

string | function

default:"{{name}}"

Naming pattern for response schemas.

parser: {
  transforms: {
    readWrite: {
      enabled: true,
      requests: '{{name}}Input',
      responses: '{{name}}Output',
    },
  },
}

boolean

default:false

Treat all object properties as required by default unless explicitly marked as optional.By default (per OpenAPI spec), missing required keyword means no properties are required. Some specifications expect the opposite behavior.

parser: {
  transforms: {
    propertiesRequiredByDefault: true,
  },
}

string | function

Rename schema component keys throughout the specification, automatically updating all $ref pointers.Useful when schema names are auto-generated or follow awkward naming conventions.

parser: {
  transforms: {
    schemaName: (name) => name.replace(/_v\d+_\d+_\d+_/, '_'),
  },
}

Pagination

string[]

Array of keywords to identify pagination fields in schemas and parameters.These keywords help plugins detect paginated operations and generate appropriate code.

parser: {
  pagination: {
    keywords: ['page', 'pageSize', 'cursor', 'limit'],
  },
}

Validation

boolean | string

default:false

Experimental: Validate the input OpenAPI specification before generating output.This is a lightweight, experimental feature with support added on an ad hoc basis.Options:

false — No validation
true or 'warn' — Validate and warn about issues
'strict' — Validate and fail on any issues

parser: {
  validate_EXPERIMENTAL: 'warn',
}

Examples

Filter to Specific Tags

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: './src/client',
  parser: {
    filters: {
      tags: {
        include: ['users', 'posts'],
      },
    },
  },
});

Exclude Deprecated Operations

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: './src/client',
  parser: {
    filters: {
      deprecated: false,
    },
  },
});

Promote Inline Enums

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: './src/client',
  parser: {
    transforms: {
      enums: {
        enabled: true,
        mode: 'root',
        case: 'SCREAMING_SNAKE_CASE',
        name: '{{name}}Enum',
      },
    },
  },
});

Custom Schema Naming

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'https://api.example.com/openapi.json',
  output: './src/client',
  parser: {
    transforms: {
      // Remove version suffixes from schema names
      schemaName: (name) => name.replace(/_v\d+$/, ''),
    },
  },
});

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Overview

Filters

Transforms

Validation

Examples

Filter to Specific Tags

Exclude Deprecated Operations

Promote Inline Enums

Custom Schema Naming

​Overview

​Filters

​Transforms

​Pagination

​Validation

​Examples

​Filter to Specific Tags

​Exclude Deprecated Operations

​Promote Inline Enums

​Custom Schema Naming

Overview

Filters

Transforms

Pagination

Validation

Examples

Filter to Specific Tags

Exclude Deprecated Operations

Promote Inline Enums

Custom Schema Naming