Missing methods with nested operation ID's with class SDKs

[opswiz]

Description

When there are two operation Id like this

"operationId": "providers.list",
and
"operationId": "tenants.providers.list",

the output is generated like this. The later, tenants.providers.list is never generated. They both are different operation IDs, the later providers belongs to tenant, which is not the providers outside.

This works fine without class sdks

// This file is auto-generated by @hey-api/openapi-ts

import type { Options as ClientOptions, TDataShape, Client } from './client';
import type { ProvidersListData, ProvidersListResponses, ProvidersListErrors } from './types.gen';
import { zProvidersListData, zProvidersListResponse } from './zod.gen';
import { providersListResponseTransformer } from './transformers.gen';
import { client as _heyApiClient } from './client.gen';

export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<
  TData,
  ThrowOnError
> & {
  /**
   * You can provide a client instance returned by `createClient()` instead of
   * individual options. This might be also useful if you want to implement a
   * custom client.
   */
  client?: Client;
  /**
   * You can pass arbitrary values through the `meta` object. This can be
   * used to access values that aren't defined as part of the SDK function.
   */
  meta?: Record<string, unknown>;
};

export class Providers {
  /**
   * List Providers
   */
  public static list<ThrowOnError extends boolean = false>(options?: Options<ProvidersListData, ThrowOnError>) {
    return (options?.client ?? _heyApiClient).get<ProvidersListResponses, ProvidersListErrors, ThrowOnError>({
      requestValidator: async (data) => {
        return await zProvidersListData.parseAsync(data);
      },
      responseTransformer: providersListResponseTransformer,
      responseValidator: async (data) => {
        return await zProvidersListResponse.parseAsync(data);
      },
      security: [
        {
          scheme: 'bearer',
          type: 'http',
        },
      ],
      url: '/v1/providers',
      ...options,
    });
  }
}

export class Tenants {
  static providers = Providers;
}

export class TenantProviders {
  static tenants = Tenants;
}

Reproducible example or configuration

https://stackblitz.com/edit/hey-api-client-fetch-example-e6ryjs6n

OpenAPI specification (optional)

{
  "openapi": "3.1.1",
  "paths": {
    "/v1/providers": {
      "get": {
        "operationId": "providers.list",
        "summary": "List Providers",
        "tags": [
          "providers"
        ]
      }
    },
    "/v1/tenants/{tenantId}/providers": {
      "get": {
        "operationId": "tenants.providers.list",
        "summary": "List Tenant Providers",
        "tags": [
          "tenants",
          "tenantProviders"
        ],
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Tenant ID"
            }
          }
        ]
      }
    }
  }
}

System information (optional)

No response

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• hey-api-client-fetch-example-e6ryjs6n (Open reproduction)

[dosubot]

This is a current limitation of class SDKs in @hey-api/openapi-ts: the generator does not support nested or dotted operationIds like tenants.providers.list as distinct methods when generating class SDKs. Only the first matching method (e.g., providers.list) is generated, and the nested one is omitted. The documentation describes that class SDKs generate method names from operationIds or operation location, but it doesn't mention any support or configuration for handling nested/dotted operationIds in class SDKs, nor any workaround to generate both methods distinctly. Flat SDKs, on the other hand, do generate both methods as expected. If you need both, using flat SDKs is currently the only documented approach see docs. If you need help exploring alternative approaches, let me know!

To reply, just mention @dosu.

---

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

[opswiz]

This missing seem to happening because the providers sharing the same methods, and the later is skipped. This confusion also happens with other operation ids too.

In another case.

the following operation ids.

providers.clients.tokens.create

& 
tenants.tokens.validate

the tokens method are clubbed into a single Tokens class, which is nested incorrectly and causing confusion. For example. providers.clients.tokens.validate is not a valid path, even though method works.

[mrlubos]

Is this a regression? Paging @flow96 as well

[opswiz]

I am not sure. My first attempt with asClass is a max stack exceeded crash. This is the first time I've successfully setup after the fix and reporting this behaviour.

[flow96]

Is this a regression? Paging @flow96 as well

No it's not a regression problem, that's how the class generation is implemented - nothing has changed there during my fixes.

How it works, given the operationIds: providers.list and tenants.providers.list:

1. We prepend the tags to the operationIds where duplicates are removed, so we end up with the following "paths":

• providers.list
• tenants.tenants.providers.list => tenants.providers.list
• tenantProviders.tenants.providers.list

2. Next each "path" is taken and split into chunks (e.g. tenants.providers.list => ["tenants", "providers", "list"]), the last chunk defines the method name (list in that case). The next chunk defines its class (providers).
   Now we proceed for every chunk and create a class if it does not already exist and link the sub classes.
   That's why tenants.providers.list and providers.list are seen as the same method, because they share the same root.

So there are two options:

1. Use unique "methods" by defining operationIds like: providers.list and tenants.providers.listByTenantId in your schema
2. Or we rewrite the class generation to use something like namespaces and do not share classes from different operationIds with each other (but that would be a lot of effort and a breaking change)

[opswiz]

Right, Those operationIds were auto generated based on the path.

But, I am wondering. Isn't providers.list and tenants.providers.list supposed to be different since they both follow different path from the root or have a different parent?

[opswiz]

If the parent is different IMO the paths shouldn't be deduplicated as we are skipping some valid paths. Otherwise the current behaviour seems fine to me.

[opswiz]

I tried speakeasy, openapi generator to see how they are working for reference. the methods are generated as expected. each operationId are grouped only if the parent is also the same, (TBH they are too complex and bloated a lot, I kinda prefer hey over them)

providers.list
providers.get

belongs to same group where ares.

providers.list // providers class
providers.get //providers class
tenants.providers.get // is providers but belongs to tenants.

in this case when name conflicts, can prefix with parent? for example

class Providers {}
class TenantsProviders{}

thoughts?

[flow96]

What happens with tags in speakeasy?
For example you have an operationId: tenants.providers.list
with tags:
[Tenants, Provider].

And also another operationId:
providers.list
with tags:
[Provider]

Are the tags being ignored?

[flow96]

When I initially wanted to fix the max call stack exception I was wondering why the current implementation is based on the tags and refactored it to use the operationId and only as a fallback use the tags.
But then the tests failed and I realized that it must be intended even though I also expected some other output of the current class generator. So I just fixed the exception instead of refactoring the generator.

The code is still on a branch in my fork here: flow96@d9e097b
But what is still missing here is the grouping based on the root class.