如何将嵌套参数添加到 tsdoc 文档答案

【问题标题】：How do you add nested params to tsdoc documentation如何将嵌套参数添加到 tsdoc 文档
【发布时间】：2022-02-10 15:08:25
【问题描述】：

下面的代码显示了可能用于注册用户的功能。请求正文接受多个嵌套参数，例如firstName、lastName 等。如何使用 tsdoc 充分记录这些嵌套参数？

    /**
     * @remarks
     * This method creates a user.
     *
     * @param  req - The request object
     * @param  res - The response object
     *
     * @returns Created user object showing the created user
     * ```
     *{
        "message": {
            "_id": "5ef3249f6a01c1006e091f92",
            "id": "1u_RGoYwV",
            "firstName": "test",
            "lastName": "User",
            "password": "$2a$10$ZQf23Qx910iJLzHO65BOO.RShufiU.YAT/IXnGQwreQ0rdoElrSQG",
            "email": "test@gmail.com",
            "avatarUrl": "https://www.image.com/cat.jpg",
    *       }
     *  }
     * ```
     *
     */

    async create(req: Request, res: Response) {
        let user = new UserModel(this.db);
        const {
            firstName,
            lastName,
            email,
            password,
            currentOrganization,
            avatarUrl
        } = req.body;
        const hashedPassword = await PasswordHelper.hashPassword(password);
        user.setFirstName(firstName);
        user.setLastName(lastName);
        user.setEmail(email);
        user.setPassword(hashedPassword);
        user.setAvatarUrl(avatarUrl);
        user.setCurrentOrganization(currentOrganization);
        await user.save();
        const users = user.get();
        res.status(200).send({ message: users });
           
    }

【问题讨论】：

标签： node.js typescript tsdoc

【解决方案1】：

从用法来看，我假设您的Request 和Response 不是原生的Request 和Response 类型，而是Express 提供的类型。

express.Request<P> 类型接受类型参数 P。该类型表示请求中提供的参数。

提供（和记录）它们的最简单方法是创建一个接口：

interface Payload {
  /**
   * First name of the user.
   */
  firstName: string;
  lastName: string;
  email: string;
  password: string;
  currentOrganization: string;
  avatarUrl: string;
  [index: string]: string;
}

将该接口提供给您的方法：

async create(req: Request<Payload>, res: Response) {

提供的参数可以在req.params 下访问——它们也有内联文档！

【讨论】：

【解决方案2】：

声明一个接口，记录那里的属性并在函数中引用该接口。

请注意，交叉引用（例如，使用 @see and @link）在编辑器中似乎并没有得到很好的支持。虽然只是有名称可能会帮助人们找到界面。

【讨论】：

谢谢让我试一试，通过谷歌搜索，这是唯一的解决方案，只是想知道我的选择，再次感谢
另见 Karol Majewski 的回答；如果您可以使用泛型更准确地键入请求，那将是最佳选择。