Documenting which API inputs come from req.query vs req.body

[TheWisestOne]

When defining an input schema for a POST/PUT API, we define the schema for the entire input object, which is a union of req.query, req.body, etc

We use express-zod-api to auto-generate API docs for our APIs, and I'm wondering if there's any way for us to specify (so the docs know) which params should come in as part of req.body and which should come in as part of req.query. I suppose from the perspective of the handler, it doesn't really matter because it all gets smashed together anyways. But for the purposes of having the documentation clearly lay out where we expect this data to be, is it possible to specify which parameters are part of which part of the input?

[RobinTail]

Well...
Currently it works the following way.
There is a distribution of inputSources which you can override in config.

1. The documentation generator can recognize the properties from the Endpoint's assigned path. In this case, if params is among the sources, it sets in: path.
2. If body is among sources (like for the POST method), it sets requestBody.
3. In other cases it sets in: query.

So it actually depicts the location of the parameters. Here are the reasons for this setup:

1. I find it beneficial that inputs are combined from the configured input sources, but
2. In encourages you to use a single channel for all your parameters.
3. I find it confusing that in POST request you have some parameters in body and others in query.
4. Using body (when available) is beneficial comparing to query, since it's JSON and accepts numbers, for example, while query always has string.

Taking this into account, do you still want to split your parameters between body and query in your documentation? @TheWisestOne

[TheWisestOne]

This explanation works for me. We had some existing apis that didn't exactly follow the paradigms you mentioned but after thinking more about it we will probably change those. Thanks for the explanation!