What's the recommended way of defining a number parameter in a path?

[Enome]

I have the spec:

/companies/{company_id}:
  get:
    summary: Show company
    tags:
      - Company
    security:
      - oat: []
    parameters:
      - in: path
        name: company_id
        schema:
          type: string
        required: true
    ...

Which will generate the following:

[path: `/companies/${number}`]: {
  /** Show company */
  get: {
    parameters: {
      path: {
        company_id: number;
      };
    };
   ...
  };

Following the examples in the docs I was expecting to be able to do this:

await api.DELETE(`/companies/{company_id}`,  {
  params: { path: { company_id: 1 } },
});

This made typescript complain about the path being passed to DELETE(), so after looking at the type definitions I realized it's expecting a number.

So then I did this:

await api.DELETE(`/companies/1`,  {
  params: { path: { company_id: 1 } },
});

So this works but it feels kinda weird having the set the company_id twice. So I was wondering if maybe I am missing something or is this the way it's supposed to work?

[drwpow]

In some ways pathParamsAsTypes (non-default behavior of openapi-typescript) doesn’t mesh perfectly with openapi-fetch. The whole idea of declaring parameters one-by-one means they can be typechecked. Even in your example, asserting company_id is a number can’t really be done in a string literal. pathParamsAsTypes starts to encroach on runtime typechecking which is what openapi-fetch is designed to avoid—it’s designed to only use ahead-of-time static typechecking and zero runtime checking for maximum performance.

When you also factor in serializing query params, that will have to be done outside of the URL anyway, so you hit a wall with pathParamsAsTypes quickly where it only helps with path params but not much else.

It should probably be a soft recommendation to avoid using pathParamsAsTypes with openapi-fetch, but I don’t want to explicitly forbid people from using it if they find it yields some utility, and they find a way to make it work for them (would love if other people provided recommendations/what they use for this option!). But just pointing out there’s more friction here than the default behavior of openapi-typescript + openapi-fetch.

[Enome]

Thanks for the swift response @drwpow.

[github-actions[bot]]

This issue is stale because it has been open for 90 days with no activity. If there is no activity in the next 7 days, the issue will be closed.

[github-actions[bot]]

This issue was closed because it has been inactive for 7 days since being marked as stale. Please open a new issue if you believe you are encountering a related problem.