web-dev-qa-db-fra.com

Comment annoter les middlewares Express avec JSDoc?

J'essaie de documenter un middleware Express, mais l'outil de validation intégré de WebStorm m'indique que les types ne sont pas affectés correctement dans le bloc JSDoc suivant:

/**
 * My middleware.
 *
 * @param {Object} req
 * @param {Object} res
 * @param {Function} next
 * @return {Object}
 */
exports.show = function(req, res, next) {
    ...
};

Dans les sources Express, je n’ai trouvé aucun @typedef pour m'aider. De plus, je veux éviter des choses comme @param {*}.

Quelle est la bonne façon de documenter le middleware Express à l'aide de JSDoc? Merci pour toute aide.

javascriptexpresswebstormjsdoc
39
Jun Thong

Tout d'abord, nous convenons que les middlewares sont des fonctions; aucune déclaration de type spécial ne sera généralement justifiée. Au-delà de cela, les intergiciels ont tendance à être fortement découplés - modular -, ce qui signifie que la balise @module est généralement applicable (et cela a de bonnes conséquences lorsque vous exécutez jsdoc).

/**
 * Description of my middleware.
 * @module myMiddleware
 * @function
 * @param {Object} req - Express request object
 * @param {Object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @return {undefined}
 */

La balise de retour est facultative selon votre guide de style, car le middleware ne renvoie pas de valeur. Enfin, contrairement à ce que prétendent Nick et mmm, le paramètre next est une fonction.

http://expressjs.com/fr/guide/using-middleware.html

Les fonctions middleware sont des fonctions qui ont accès à l’objet request (Req), à l’objet réponse (res) et à la fonction middleware suivante Dans le cycle requête-réponse de l’application. La fonction middleware suivante est communément désignée par une variable nommée next.

next n'est pas une préparation sophistiquée interne à Express; Express transmet à chaque fonction middleware la requête, la réponse et la fonction middleware suivante dans la pile, comme suit:

mw1 = function(req, res, next){}.bind(undefined, req, res, mw2)
mw2 = function(req, res, next){}.bind(undefined, req, res, mw3)

La valeur de next dans la portée de mw1 est mw2.

6
jeff_mcmahan

Utilisez DefinitelyTyped

  1. Installer les types express npm install --save-dev @types/express
  2. utilisez e.Response as habituellement @param {e.Response} res

Plus de types

  • dans le fichier /node_modules/@types/express/index.d.ts
  • pour Réponse c'est e.Response parce que:

... declare namespace e { ... export interface Response extends core.Response { } ...

WebStorm

installer les types via Paramètres> Langages & Frameworks> Javascript> Bibliothèques> @ types/express

3
Michal Miky Jankovský

Vous pouvez non seulement JsDoc les types de paramètres et les descriptions, mais aussi leurs membres attendus.

/**
 * 
 * @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){
}
1
Steven Spungin

req, res et next sont tous des objets, et un middleware ne renvoie généralement pas, les éléments suivants peuvent donc être utilisés. 

/**
 * My Middleware
 * @name MyMiddleWare
 * @function
 * @param {Object} req
 * @param {Object} res
 * @param {Object} next
 */
0
bambam

La seule chose que vous devez changer est le @param {Function} à côté de @param {Object}. De plus, @return devrait décrire ce que la fonction retourne; par exemple, (Object, Array) ou une combinaison ({Object|Null})

0
Nick