How do I jsdoc parameters to web request?

Question

I have functions like this (in Node.js/Firebase) and wonder how to add documentation i JSDoc format:

exports.getUserRes = functions.https.onRequest(async (request, response) => {...}

How do I document the GET/POST/etc parameters to the request?

Answer 1

I combine other answer in How to annotate Express middlewares with JSDoc? and modify some code,
it could include all of the methods/properties defined on express.Request and event custom request body.
It could not only use in request.body, but also support in req.query.
That because express.Request support generics, so we could use this in JSDOC.

First, remember to install @types/express with npm install --save-dev @types/express.

Second, setup like following code.

// @ts-check
/**
 * @typedef {object} showRequestBody
 * @property {string} name this is name in request body
 * @property {number} age this is age in request body
 * 
 * @typedef {object} showRequestQuery
 * @property {string} name this is name in query
 * @property {number} age this is age in query
 * 
 * @param {import('express').Request<{}, {}, showRequestBody, showRequestQuery>} req
 * @param {import('express').Response} res 
 * @param {import('express').NextFunction} next 
 */
exports.show = function(req, res, next) {
};

Note: I use it in vscode.

---

other methods/properties defined on express.Request, for example req.headers

---

req.body hint

---

req.query hint

Answer 2

I just found an old question with an answer that seems to suggest a good way. It is not the accepted answer there I mean, but the answer by @Steven Spunkin:

javascript - How to annotate Express middlewares with JSDoc? - Stack Overflow How to annotate Express middlewares with JSDoc?

I am copying his answer here for simplicity. Comments are welcome!

/**
 * 
 * @module myMiddleware
 * @function
 * @param req {Object} The request.
 * @param res {Object} The response.
 * @param req.params.foo {String} The foo param.
 * @param req.query.bar {String} The bar query.
 * @param req.body {Object} The JSON payload.
 * @param {Function} next
 * @return {undefined}
 */
function foo(req, res, next){ ... }