OpenAPI Code Generation — Parser Filters & Sort Order#

@hey-api/openapi-ts parses an OpenAPI specification and runs it through a plugin pipeline before emitting TypeScript types, Zod schemas, and service clients. The parser config block is the primary place to trim and reshape input before any plugin sees it.

Full reference: Parser | Hey API

Tag-Based Filtering#

Operations can be filtered by their OpenAPI tags via parser.filters.tags. Both include and exclude accept arrays of exact strings or JavaScript-style regular expressions (e.g., '/^v2/'). 1

include — only operations carrying at least one of these tags are emitted.
exclude — operations carrying any of these tags are dropped.
Precedence: when both rules match the same tag, exclude wins. 1

The same include/exclude/precedence pattern applies to the other filter axes: operations, schemas, parameters, requestBodies, and responses. 1

Orphaned resources#

By default, when any filter is active, resources left unreferenced ("orphans") are also dropped (orphans: false). Set orphans: true to retain them. 1

Sort Order of Generated Output#

Default behavior (performance-optimized, non-deterministic)#

For performance reasons, @hey-api/openapi-ts does not preserve original specification order when filtering is applied. This means the output order of types, Zod schemas, and other generated files can differ from the input order—and can vary between runs. 1

preserveOrder#

Set parser.filters.preserveOrder: true to restore deterministic, spec-order output: 1

parser: {
  filters: {
    preserveOrder: true,
  },
},

Known bug: reverse sort when using parser.filters.tags.exclude (Issue #3952)#

Adding parser.filters.tags.exclude causes generated types and Zod schema files to be sorted Z → A instead of A → Z. This is a confirmed bug (labeled bug 🔥). 2

Workaround: enable preserveOrder: true to bypass the broken sort path, or avoid the exclude option until the bug is resolved.

Named import sorting (Issue #2666)#

A separate quality-of-life feature to alphabetically sort named imports inside generated files was requested and closed via PR #2668. 3 The reverse-sort bug in issue #3952 was first reported as a comment in that thread. 2

Custom Symbol Placement (advanced)#

The parser.hooks.symbols.getFilePath hook lets you override which output file a generated symbol lands in—enabling patterns like alphabetic sharding. 1

Quick Reference#

Primary docs: Parser Configuration
Active bug: #3952 — reverse sort with tags.exclude