Reference an operation to its path (or vice versa)

[bennettdams]

Hey!

I generate paths and operations, but both of them cannot be referenced to each other.
The path uses the operations's type, but there is no way in TypeScript to know that this path is for this operation.

What I was trying to do:
Create a function for that operation. It should take the request body as a parameter. But I cannot allow both type-safety for a) the path and b) the operations' request body together, because the types don't know of each other.

For example:

export interface paths {
    "/some-operation": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        get?: never;
        put?: never;
        /**
         * Tare balance
         * @description Tares the balance.
         */
        post: operations["someOperation"];
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
}

The path some-operation uses someOperation to describe post, but one cannot reference them afterwards.

Is there something I am missing? Maybe a CLI flag? I even tried to use operationId in my schema, but that does not help.

This could be fixed by having a 1-to-1-mapping of each path and its operation. Either via a field in each paths entry or via a new type that just maps them together.

[drwpow]

This is possible with Operation IDs today. There’s one export interface operations that includes everything with a unique ID. You do just include operationId on the operation.

These are in all the examples and we have tests to catch this; is there an error in your schema anywhere?

[bennettdams]

Thanks for the answer!
When I added operationId to my schema, the entry in operations was exactly that ID – all good. But even with that ID I cannot reference a path, right?

Example (someOperationId coming from the schema):

export interface paths {
    "/some-operation": {
        ...
        post: operations["someOperationId"];
        ...
    };
}

export interface operations {
    someOperationId: {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        ...
  }
}

How would TypeScript know that these two are related to each other?

[ruben-brugman-ispnext]

@drwpow Could you provide and example of how to use the OperationId to build up a request instead of using the HTTP method & API path? In our API spec we have made it a requirement to always specify the OperationId for all endpoints. Our endpoints paths are still subject to change, however the OperationIds are pretty constant. So I would prefer refencing the OperationId over using the direct API path for the generated client.

Currently I have a useSupenseQuery like this:

export const useBudget = () => {
  return ApiClient.getTanStackQueryInstance().useSuspenseQuery(
    "get",
    "/api/analytics/v2/budgets",
  );
};

My preference would be something like this:

export const useBudget = () => {
  return ApiClient.getTanStackQueryInstance().useSuspenseQuery(
    operations["ReadAllBudgets"]
  );
};