如何在Web请求中使用JSDoc参数？

Question

我有类似这样的函数（在Node.js/Firebase中），想知道如何在JSDoc格式中添加文档：

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

我应该如何记录GET/POST等参数到请求中的request中？

- Leo

Answer 1

我结合了如何使用JSDoc注释Express中间件？中的其他答案并修改了一些代码，
它可以包括在express.Request上定义的所有方法/属性和自定义请求体。
它不仅可以在request.body中使用，还支持在req.query中使用。
这是因为express.Request支持通用类型，所以我们可以在JSDOC中使用它。

首先，请记得使用npm install --save-dev @types/express安装@types/express。

其次，设置如下代码。

// @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) {
};

注意：我在 VSCode 中使用它。

---

express.Request 定义了其他的方法和属性，例如 req.headers

---

req.body 提示

---

req.query 提示

- Jack Yu

---

如果我想在res对象中添加自定义属性，如何使用jsdoc进行注释...是使用req.error()还是req.success()？ - undefined

Answer 2

我刚发现一个旧问题，其中有一个回答似乎提供了一个好方法。我的意思不是那里被接受的答案，而是@Steven Spunkin的答案：

javascript - 如何使用JSDoc注释Express中间件？-堆栈 溢出 如何使用JSDoc注释Express中间件？

为了简单起见，我在这里复制了他的答案。欢迎评论！

/**
 * 
 * @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){ ... }

- Leo