Override operationId (?)

[th3l0g4n]

We use Kubb to generate Clients for various Services (written in Java and SpringBoot).
From time to time it happens, that "named operations" collide (e.g. getUsers in controllerA and getUsers in controllerB) because a new Entity or whatever is introduced.
The OpenAPI generator suffixes these operationIds with a number.

When Kubb now generates the files (also types, query functions, etc) it MIGHT happen, that what was:
getUsers --> /api/group/users
is now becoming
getUsers1 --> /api/group/users
because of a new operation which is now called getUsers but points to a different api endpoint:
getUsers --> /api/company/users

This also applies to filenames, Typescript types etc. Everything might get a number suffix and suddenly your calls pointing towards the wrong endpoint.

Does anyone else has trouble with this kind of issue? Is there any config option Kubb-wise to stabilize the generated content?

[dosubot[bot]]

Hi @th3l0g4n! I'm Dosu and I’m helping the kubb team.

This is a common issue! Kubb provides a few options to help stabilize generated output when operationIds collide:

1. Use transformers.name to customize operation naming across plugins:

pluginClient({
  transformers: {
    name: (name, type) => {
      // Add custom prefix/suffix logic here
      return name
    }
  }
})

This works in @kubb/plugin-ts, @kubb/plugin-client, @kubb/plugin-react-query, etc. See docs.

2. Enable collisionDetection (v4.19.2+) in plugin-oas:

pluginOas({
  collisionDetection: true
})

This prevents duplicate identifier errors by adding prefixes based on schema/property names rather than just numeric suffixes. Note: this primarily applies to schema names.

3. Group by tags to organize files by controller:

group: {
  type: 'tag',
  name: ({ group }) => `${group}Controller`
}

Root cause recommendation: The most stable solution is ensuring unique operationId values in your OpenAPI spec at the source (Java/SpringBoot side). Kubb relies heavily on operationId as the primary identifier — without unique values, path-based naming inevitably causes collisions.

If you're generating OpenAPI from SpringBoot, you might be able to configure springdoc-openapi or your OpenAPI generator to produce unique operationIds (e.g., controllerA_getUsers instead of just getUsers).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}