Deprecation of apiParam

[NicolasCARPi]

At first there was only @apiParam which acted for both the query part (in the url), and the body (payload). Now we have @apiQuery and @apiBody to clearly separate the two different kind of parameters.

I believe @apiParam should be deprecated and then removed completely as it is only confusing and doesn't make much sense IMHO.

What do you (the users) think about this? Is there a good reason to keep @apiParams around?

[rottmann]

Only for old compatibility let apiParam map to apiBody, but we should remove it from docs.
It could throw a warning when somebody use apiParam.

But i don't have any problem to remove it completely, a quick search and replace should be no problem in maintained projects.

[canonex]

It could throw a warning when somebody use apiParam.

I think it would be very useful.
In my case this would have solved itself this: #1149

Thank you,
Riccardo

[jerrens]

I thought @apiParam was used to describe the named route parameter variables within the URI route itself and @apiquery was used for the variables after the '?' char of the URI.

If using Express: app.get('/api/group/:param1/:param2', controller); then, the call to
GET https://domainName/api/group/foo/bar?query1=val1&quert2=val2

where inside the controller(req, res) middleware:
req.params.param1 = foo
req.params.param2 = bar
req.query.query1 = 'val1'
req.query.query2 = 'val2'

Would be described with:
@apiParam {string} param1 The description of Param1's use
@apiParam {string} param2 The description of Param2's use
@apiQuery {string} [query1=''] The description of how query1 is used for filtering the response
@apiQuery {string} [query2=''] The description of how query1 is used for filtering the response

[NicolasCARPi]

You make a good point.

[dtslvr]

I'm trying to migrate from @apiParam to @apiBody, but I'm missing @apiBodyExample (similar to @apiParamExample).

[NicolasCARPi]

See: #1196

[dtslvr]

See: #1196

Thanks for creating a ticket @NicolasCARPi 🙂