[openapi-ts] Feature Request: Configurable Output modes

[nikitastryuk]

Firstly, I would like to extend my gratitude for the outstanding work. It is an invaluable tool, and I truly appreciate the effort and dedication that has gone into it.

I would like to propose an enhancement particularly for users managing large projects and openapi specs. This feature would enhance searchability, navigation, and overall management of generated files.

Feature Proposal: Configurable Output Generation Modes

It introduces tags-split mode that organizes tag-specific (openapi tag) files into directories while retaining all core files.

Example Configuration:

{ output: { path: 'src', mode: 'tags-split' } };

Modes

1. Client-based (Current Implementation)

• Description: All logic (client, SDK, types) is bundled into a few core files.

• Example:

  /src/
    client.gen.ts
    sdk.gen.ts
    types.gen.ts
    index.ts
    @tanstack/react-query.gen.ts
  

2. Tags-split Mode

• Description: Files are grouped by openapi tag (e.g., pets, users) into folders, keeping core files intact.

• Example:

  /src/
    pets/
      pets.client.ts
      pets.sdk.ts
      pets.types.ts
      index.ts
      @tanstack/pets.react-query.gen.ts
  

3. Per-request Mode

• Description: The generated files will be broken down by each operation:

• Example:

/src/
  pets/
    create.pet.client.ts
    create.pet.sdk.ts
    create.pet.types.ts
    read.pet.client.ts
    read.pet.sdk.ts
    read.pet.types.ts
    update.pet.client.ts
    update.pet.sdk.ts
    update.pet.types.ts
    delete.pet.client.ts
    delete.pet.sdk.ts
    delete.pet.types.ts
    index.ts
    @tanstack/pets.react-query.gen.ts

I believe there could be several more useful options, such as a single-file option for really tiny projects. However, I’m personally more interested in the tags-split option, as navigating a single file that contains all domains can be quite difficult.

[mrlubos]

Hi @nikitastryuk and thank you! I'm onboard with this, it just hasn't been prioritised.

When you mention navigating a single file, can you describe what you're looking for in that file? Personally, I rarely go into the generated files and my spec is 36k+ lines of pretty JSON. This is for my own context, not directly related to the request

[nikitastryuk]

I usually look for newly generated TypeScript interfaces, hooks, and APIs in the code when integrating new endpoints. Scanning through Swagger or specs feels much slower and less comfortable (maybe that’s just me 😄).

I believe grouping these into logical modules based on OpenAPI tags (or even using per-tag + per-request option) would make this process easier. In my experience working with a disconnected backend team, the generated code often served as our main source of truth. While team did visually parse the Swagger/OpenAPI spec when necessary, having a well-structured codebase often allowed us to skip that step entirely and jump straight into the newly generated module folder to start integrating. It saves time and improves clarity imo.