orpc: [OpenAPI] Scalar/Swagger handle oRPCs default OpenAPI spec config for array query param values incorrectly
Issue
It appears both Scalar and Swagger default to querying for array query string param values in this format:
http://some.domain.com/api/endpoint?someVar=someValue1&someVar=someValue2
When this happens, it seems that the default ZodSmartCoercionPlugin() only parses the last instance of the query param as string value instead of combining the duplicates into an array value.
Recreation
I recreated this in a branch from the “Contract-FirstPplayground” stackblitz: https://stackblitz.com/edit/github-7qeqofgp?file=src%2Fcontract%2Fplanet.ts
You can recreate this just by adding any input param that is a zod array:
export const findPlanet = oc
.route({
method: 'GET',
path: '/planets/{id}',
summary: 'Find a planet',
tags: ['Planets'],
})
.input(
z.object({
id: z.number().int().min(1),
other: z.enum(['a', 'b', 'c']).array().optional(), // <-- This will get parsed incorrectly when the requested from Saclar or Swagger
})
)
.output(PlanetSchema);
Then calling that endpoint with that array param set to any or multiple values in Scalar or Swagger UIs will result in this request:
http://localhost:3000/api/planets/1?other=c&other=a
A validation input error will get thrown because other is parsed to just the value "a" instead of the value ["c", "a"]:
Additional Notes
Making this same call from a JsonifiedClient OpenAPILink client does not result in this issue, since I assume it is encoding the array into only a single query string param definition.
I don’t believe this is a limitation of Swagger at least. Given we had this same setup working with Swagger in TS-Rest. Perhaps there is a value that can be set in the OpenAPI spec to tell these UI clients to generate the query string value differently here?
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Reactions: 1
- Comments: 27 (23 by maintainers)
I do not even have this problem at all. For now I do not use parameters arrays in my project(and if I will be I will find a way to make it work for myself).
Why I chimed in on this issue? Main thing for people which will jump in to try oRPC instead of trpc(or smth else) would be openapi compatibility(there are others cool features of course but openapi compatibility is one of the main selling points). And a lot(A LOT) of people and companies will use swagger or other openapi compatible tools and they will expect it to work. Some of them will already have some existing openapi spec(contract in terms of orpc) to integrate. And if it will not work they will just move on, skip oRPC.
So that is why I think making as seamless and fully OpenAPI spec compatible solution is really important. So that generated spec will be fully compatible. Either via a plugin or anything, any way, you know better @unnoq
Just so that OpenAPI spec generated by oRPC will be OpenAPI compliant/compatible and when you paste it into https://editor-next.swagger.io/ it will not show any errors.
The main point is to make oRPC succeed. And from my experience openapi compliance will bring all those enterprise companies which highly rely on swagger/openapi. I tried to pitch different tools(including trpc) in companies I worked for and in all cases I got rejections because of swagger/openapi compatibility…
@tresorama while yes you can manually adjust params and naming to use the bracket notation in scalar. The original goal of this issue was to ask if we could get the OpenAPI spec that oRPC generates by default to adjust its formatting so that you don’t have to manually do that everywhere all the time.
Instead it’d align a bit better with how other tools interpret the spec here so where we have params that are array values, everything just works out of the box.
I get that might be trickier with multipart forms, but just wanted to make sure we’re all on the same page here. It seems like @valerii15298 is at least. Bracket notation is fine, makes perfect sense, and totally should still be supported - but it might not be relevant to enabling Scalar/Swagger to handle array params correctly here out of the box.
Yes formatting the request like that does work. Sorry, perhaps I’ve titled this issue incorrectly here.
The real issue I’m calling out is that by default, oRPC’s OpenAPI spec generator does not generate a spec that configures tools like Scalar or Swagger to make requests for array params like in a valid way - either with this notation or via json encoded values. The programmatic orpc/client works fine since it serializes the value for json. But you’d need to configure the generated OpenAPI spec.json output differently in order for these kind of params to work out of the box in Scalar/Swagger I believe.
Unrelated, but oRPC is an awesome library! Your packages and APIs are very well thought out. We started investigating using oRPC alongside NestJS as an alternative to our current TS-Rest setup, but oRPC covers almost all of our needs so we’re currently testing out a migration away from NestJS to a pure oRPC setup entirely!
The recent “standard schema” movement, that aim to consider any validation library interchangable is not applicable ? I never used standard schema so I dont know much
The oRPC core shouldn’t depend on any specific library or framework. If there is a standard way to do it, we can consider it. oRPC still works well without it.
A plugin can handle it instead, like ZodSmartCoercionPlugin.
What i read behind the lines of some comments is that the deserialization/parsing of request data should depend on the
inputschema of the procedure.@unnoq You opted to not doing that, but keeping deserialization/parsing un-aware of the input schema validation. Which were the reasons if you can share?
@unnoq
But
style: deepObjectdoes not support arrays inside objects or vice versa too. I found that complex parameters could also be specified and serialized using:Maybe this could be the solution to deeply nested data inside parameters?
Found this in their examples https://spec.openapis.org/oas/latest.html#parameter-object-examples :
Looks like any nested object could be there(as long as it fits into size of url) and this approach could be the solution.
Maybe for simpler cases just to use default
style: formand for more complex ones this way? But that is for you to decide 😄 😉These specs are quite tricky and at the same time interesting to read and ^decipher^ 😃 😃 😃
Actually, we configured the parameter with
"style": "deepObject", which may not be a widely known OpenAPI style.I think we can support multiple query parameters with the same name as an array rather than overriding previous values