好的，所以我在使用 apidocjs 来解决它，然后在生产环境中实现它并且遇到以下问题：
~/apidoc_playground$ apidoc
warn: parser plugin 'param' not found in block: 0
info: Done.
以下是它正在查看的块注释（每个都在一个单独的文件中）：
/**
*this is a test of apidocjs
*@api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
*/
/**
*@api {GET} /getPicture/:UID Retreive user profile picture
*@apiGroup User
*@apiName getPicture
*@apiVersion 0.0.1
*
*@apiDescription userID goes in, picture comes out, you can't explain that!
*@apiParam {int} UID User's identification number.
*@apiExample {curl} Example usage:
* curl -i http://api.example.com/getPicture/45123
*@apiSuccess (200) {json} picture The user's profile picture
*@apiError (4xx) {userNotFound} UID There was no user affiliated with the given id.
*@apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error":"UserNotFound"
* }
*/
我已经知道的：
这不会导致更新失败，apidoc 会按预期更新输出目录。
如果我在调用 apidoc 之前删除了输出目录，则没有警告。
如果没有要解析的文件，警告仍然会出现。
在寻找答案之后，我能找到的最多的是一个与我的问题相似的问题，除了提问者在他的 apidoc.json 中也有格式错误。话虽如此，该线程中的答案并不能真正满足我的要求（一个是在调用 apidoc 之前删除输出文件夹，另一个是如果您想保留历史记录，则不要删除输出文件夹，也许你有格式错误）。
来自更有经验的 apidocjs 用户的任何见解都会受到欢迎。
对不起文字墙