Discussion: Migration strategy for oazapfts v6 → v7 in `@rtk-query/codegen-openapi`

[Suto-Michimasa]

Context

To support enumStyle (#5223), we need to upgrade oazapfts from v6 to v7. However, v7 removes the ApiGenerator class and oazapfts/generate export path entirely — the semi-official APIs that codegen currently depends on. The new public API is limited to createContext (oazapfts/context), UNSTABLE_cg, and generateAst (oazapfts).

In #4265, @Xiphe notified that v7 would remove these APIs, and a Plugin System is in early development (oazapfts#805).

Migration options

Option A: Reimplement lazy type generation locally

Compatibility adapter (~400 lines) using v7's createContext + UNSTABLE_cg, reimplementing the removed ApiGenerator behavior.

• Pro: Preserves v6's lazy architecture — types are created on-demand per $ref, so filterEndpoints works naturally.
• Con: ~400 lines of type generation logic that needs manual sync when oazapfts evolves.

Option B: Use generateAst + post-filter unreferenced types

Use v7's generateAst(ctx) to generate all types upfront, then filter out types not referenced by selected endpoints.

• Pro: Delegates type generation to oazapfts — bug fixes and new features are inherited automatically.
• Con: Requires AST-based transitive closure to determine referenced types. Circular references and discriminator patterns make this non-trivial.

Proof of concept

I have a working implementation of Option A that passes all 73 existing tests, including enumStyle: 'union' | 'enum' | 'as-const' support and proper handling of discriminator patterns, readOnly/writeOnly, and unionUndefined. Happy to share as a draft PR, or pivot to another approach.

Questions

1. Which migration approach is preferred? Option A is ready now but adds maintenance; Option B delegates more but requires filter logic. Or should we wait for the Plugin System (Oazapfts will get plugins #4265) instead?
2. Is it worth coordinating with @Xiphe on what RTK codegen would need from the plugin API?
3. Should the v7 migration be a separate PR from enumStyle? The migration is a prerequisite, but splitting might make review easier.

Related

• feat(codegen): Expose enumStyle option from oazapfts v7.3.0 #5223 — enumStyle feature request
• Oazapfts will get plugins #4265 — oazapfts Plugin System notification (maintainer discussion)
• Update oazapfts to 6.1 #4588 — Previous oazapfts update (v6.1)
• oazapfts#805 — Plugin System PR
• oazapfts#823 — enumStyle in oazapfts

[Suto-Michimasa]

I've opened a draft PR as a rough PoC for Option A: #5228

It's still a work in progress, but should give a concrete picture of what the approach looks like. Feedback welcome.

cc: @markerikson @aryaemami59 @EskiMojo14

[aryaemami59]

@Suto-Michimasa awesome, thanks! Would you be open to splitting this into two separate changes—one PR for the v7 migration, and a follow-up PR for adding useEnum? That would make the review and potential rollback much easier.

[Suto-Michimasa]

@aryaemami59
Sure, I'll split it into

1. v7 migration (compatibility adapter)
2. enumStyle option as a follow-up

I'll update this PR to be migration-only and open a separate one for enumStyle.

[aryaemami59]

@Suto-Michimasa Awesome thanks a million!

[Suto-Michimasa]

@aryaemami59
Updated! This PR is now migration-only (removed enumStyle and lowered the minimum to ^7.0.0). Ready for review when you get a chance.

[aryaemami59]

@Suto-Michimasa Awesome, I'll take a look as soon as I get a chance.

[Xiphe]

Hey everyone. Sorry for chiming in late.

When you actively work on this I'd be more then happy to jump on the train and establish the plugin hook points that you need.
I'll have a look at it myself over the weekend and happy to jump on a collaboration that makes the implementation on your end more straight forward (which was the idea of the plugin system all along)

[Suto-Michimasa]

@Xiphe Thanks for the offer! Would love to collaborate.

PR #5228 currently reimplements lazy type generation using createContext + UNSTABLE_cg. The key hooks RTK codegen would need:

• Lazy/on-demand type generation — types created per $ref as endpoints are processed (not all upfront), so filterEndpoints works naturally
• Per-endpoint code generation control — select which operations to generate
• Access to schema-to-type mapping — discriminator patterns, readOnly/writeOnly, unionUndefined
  Happy to use the current adapter as a bridge until the plugin API covers these.

cc @aryaemami59 @markerikson — any thoughts?