feat(openapi-typescript): new feature to generate a subset of the api definition by filtering paths

[tqml]

Add pathsFilter option to generate a subset of API paths

Motivation

Generated TypeScript clients for large APIs (e.g. GitHub, Stripe) can be extremely large — tens of thousands of lines — even when a project only consumes a handful of endpoints. There was no way to scope the output to a relevant subset without manually editing the schema file.

Note: the code was written and reviewed by AI, but also again reviewed and tested by me.

What this PR does

Adds a new pathsFilter option to OpenAPITSOptions:

const ast = await openapiTS(schema, {
  pathsFilter: (pathname, method) => pathname.startsWith("/repos") && method === "get",
});

• The callback receives each (pathname, method) combination and returns true to include it or false to exclude it
• After path filtering, the generated output also tree-shakes component schemas — any $ref targets no longer reachable from the included paths are removed transitively, so unused models don't appear in the output
• method is always lowercase; pathname is passed as-is (OpenAPI paths are case-sensitive and are not normalized)
• Limitation: path items defined as a $ref (e.g. "/users": { $ref: "..." }) are always included regardless of the filter, since individual methods cannot be inspected without resolving the reference. This is documented in the JSDoc.
• The new PathsFilterFn type is exported from the package for consumers who want to explicitly type a standalone filter function

Files changed

File	Change
src/lib/filter.ts	New — applyPathsFilter implementation with transitive ref tree-shaking
src/index.ts	Apply filter after validateAndBundle, before AST transformation; export PathsFilterFn
src/types.ts	Add pathsFilter to OpenAPITSOptions with full JSDoc
test/lib/filter.test.ts	302-line test suite covering path/method filtering, tree-shaking, transitive refs, circular refs, mutation safety
examples/github-api-pulls-only.ts	Generated example — GitHub API scoped to the Pulls endpoints only
scripts/generate-github-pulls-only.ts	Script used to generate the above example
scripts/update-examples.ts	Wired the new example into the existing example update pipeline

AI disclosure

This feature was implemented, tested, and reviewed with the assistance of Claude (Sonnet 4.6) in May 2026 using the following prompt:

I'm using openapi-typescript @packages/openapi-typescript/ to generate my api clients. One problem, these clients can become HUGE so i would like to add an option to only include specific openapi paths.

For example if an api has the following paths:

• GET /users
• GET /users/:id
• POST /users

i would like to be able to specify to only include GET /users/:id and GET /users and all other routes should be ignored. This means the generated output typescript file, should also remove all paths (and ideally all schema models for this values)

A subsequent code review session identified and addressed the following:

• Documented that $ref path items bypass the filter (known limitation)
• Added clarifying note that method is always lowercase and pathnames are not normalized
• Exported PathsFilterFn from the public API

[netlify]

👷 Deploy request for openapi-ts pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	9cc5335

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9cc5335

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR