Path params

[dodas]

Hey @jlalmes, this is a great little library!

I am exploring possibilities and as far as I can understand, there is currently no way to define a path parameter.
Consider the petstore swagger example, the uploadFile has petId parameter, which is part of the path.

Could we try to extract the path params by looking for curly braces in meta.openapi.path, and then find param with the same name in input and mark that param as from: "path" instead of from: "query"?

WIP attempt to implement the above approach: v0.1.0...dodas:feat/path-parameters

Have you thought about supporting this use case?
I am happy to discuss this and potentially take a stab at implementing it.

Thanks!

[jlalmes]

I did initially consider adding path parameter support when creating this library, but I decided to leave it out as an unsupported feature due to tRPC having no similar concept and the DX getting somewhat complicated.

I'm open for adding support if there is a use-case though, could you explain your requirement for GET /user/some-user-id instead of GET /user?id=some-user-id?

[dodas]

I think using path parameters for identifying an item within collection is a common (best) practice.
See from the docs:

They (path parameters) are typically used to point to a specific resource within a collection, such as a user identified by ID

We currently already have a couple of rest endpoints with path parameters and we are now trying to migrate them to trpc-openapi without making breaking changes to our public API.

What do you think about my proposed solution? It seems the model remains quite straightforward, where input object still remains the truth of source for all your parameters, but then those ones that are "mentioned" in path would be considered path parameters instead of query params.

[jlalmes]

We currently already have a couple of rest endpoints with path parameters and we are not trying them to migrate to trpc-openapi without making breaking changes to our public API.

Ok, let's support this!

Breaking change

Input for queries are restricted to ZodObject({ [string]: ZodString }) schema, however input for mutations are currently unrestricted as any ZodType. The proposed solution introduces a breaking change requiring mutation input to follow a ZodObject({ [string]: ZodType }) schema.

I don't think isn't a huge issue (currently in alpha) but just wanted to raise.

Usage

trpc.router()
  .query('getUserById', {
    meta: { openapi: { enabled: true, method: 'GET', path: '/user/{userId}' } },
    input: z.object({ // validated as ZodObject({ [string]: ZodString })
      userId: z.string(), // `userId` is required in schema because it is used in path
      teamId: z.string(),
    }),
    output: ...,
    resolve: ...,
  })
  .mutation('updateUserById', {
    meta: { openapi: { enabled: true, method: 'PUT', path: '/user/{userId}' } },
    input: z.object({ // validated as ZodObject({ [string]: ZodType })
      userId: z.string(), // `userId` is required in schema & validated as ZodString
      details: z.object({
        name: z.string(),
      }),
    }),
    output: ...,
    resolve: ...,
  })

Obviously paths with multiple parameters should be supported too e.g./team/{teamId}/user/{userId}

GET /user?userId=user_123
> 404 NOT_FOUND

GET /user/user_123
> 400 BAD_REQUEST

GET /user/user_123?teamId=team_123
> { userId: 'user_123', teamId: 'team_123' }

GET /user/user_123?teamId=team_123&userId=user_456 // do not overwrite
> { userId: 'user_123', teamId: 'team_123' }

POST /user {"userId":"user_123"}
> 404 NOT_FOUND

POST /user/user_123
> 400 BAD_REQUEST

POST /user/user_123 {"teamId":"team_123"}
> { userId: 'user_123', teamId: 'team_123' }

POST /user/user_123 {"teamId":"team_123","userId":"user_345"} // do not overwrite
> { userId: 'user_123', teamId: 'team_123' }

A quick scan of your PR looks great, I will review properly and add to docs + some tests tomorrow.

Thanks @dodas!

[dodas]

Great! Happy to hear this.
Let me know if there is anything I can do to help with this.

[jlalmes]

Hi @dodas, support for path parameters has just shipped, thanks for your help! 🚀

Please can you upgrade to trpc-openapi@0.1.0-alpha.20 & let me know if you find any issues. Keen to release v0.1.0 soon - so feedback is appreciated.

[dodas]

Perfect, thanks!!
From testing so far, everything seem to work as expected 💯