解決nodejs使用apidoc問題：Cannot read property 'Filter...' of undefined

apidoc是什麼？

apidoc 是一個根據源代碼中api註解創建api文檔的工具，輕便易用。

問題背景

• 現象：nodejs中使用apidoc在控制檯報如下錯誤：

require.min.js:19 TypeError: Cannot read property 'Filter...' of undefined
    at Object.__ (locale.js?v=1579071667889:35)
    at Object.<anonymous> (handlebars_helper.js?v=1579071667889:43)
    at Object.eval [as main] (eval at createFunctionContext (handlebars.min.js?v=1579071667889:28), <anonymous>:6:97)
    at c (handlebars.min.js?v=1579071667889:27)
    at d (handlebars.min.js?v=1579071667889:27)
    at e (handlebars.min.js?v=1579071667889:28)
    at main.js:295
    at Object.execCb (require.min.js:30)
    at ea.check (require.min.js:18)
    at ea.<anonymous> (require.min.js:23)

頁面顯示爲空白:

• 軟件環境：
  • apidoc 版本：0.19.1
  • 操作系統 macOS 10.14.6
  • Google chrome 版本 79.0.3945.117（正式版本）
  • node v10.16.3
• 測試源代碼

const Koa = require('koa');
const util = require('util');
const app = new Koa();
const helper = require('./helper');

let logger = helper.getLogger('logTest');

const router = require('koa-router')();

const handler = async (ctx, next) => {
    try {
        console.info("==>handler");
        await next();
        console.info("<==handler");
    } catch (e) {
        console.info('e.err:', e.err);
        console.info('e.status:', e.status);
        ctx.response.statusCode = e.status || e.err || 500;
        ctx.response.body = 'errrrrrrrrr';
        // console.error("error::", e);
        // console.error("error::", e.toString());
        // console.error("error::", e.toLocaleString());
        // console.error("error::", e.status);
        // console.error("error::", typeof e);
        // console.error("error::", e.valueOf());
        // console.error('err msg:', e.message);
        console.info("1<==handler");
        // ctx.app.emit('error', e, ctx)
        console.log(e.message === 'file_not_found');
        ctx.app.emit(e.message, new Error("log file can't be found"), ctx);
    }
};

app.use(handler);


/**
 * @api {post} /api/User/register 用戶註冊
 * @apiDescription 用戶註冊
 * @apiName Register
 * @apiGroup User
 * @apiParam {string} name 用戶名
 * @apiParam {string} password 密碼
 * @apiVersion 1.0.0
 */
app.use(router.get('/test', async ctx => {
    console.log("test log");
    ctx.throw(new Error(util.format('file_not_found:%s', 'asdfasdf')));
}).routes());

app.listen(3000);
console.log("ready for service");

app.on('file_not_found', (err, ctx) => {
    // console.error("file not found error:", err, ctx);
    // logger.error("file not found error: %s, ctx:%s", err, ctx);
    logger.error("err:", err);
    logger.info("--============================");
    logger.error("%s, ctx:%j", err.stack, ctx);
    // console.error('err stack:', err.stack);
});

• 使用到的package.json

{
  "name": "koa-demos",
  "version": "1.0.0",
  "description": "a collection of simple demos of Koa",
  "scripts": {
    "dev": "cross-env NODE_ENV=dev nodemon demos/test/logtest.js",
    "prod": "cross-env NODE_ENV=prod node demos/test/logtest.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "apidoc": {
  	"template": {
    	"forceLanguage": "zh-cn"
  	},
    "title": "apiDoc在瀏覽器中的標題",
    "url": "api.github.com/v1"
  },
  "keywords": [
    "Koa",
    "Node"
  ],
  "author": "Li Yi",
  "dependencies": {
    "cross-env": "^6.0.3",
    "express-validator": "^6.3.0",
    "fs.promised": "^3.0.0",
    "koa": "^2.3.0",
    "koa-body": "^2.3.0",
    "koa-bodyparser": "^4.2.1",
    "koa-compose": "^4.0.0",
    "koa-parameter": "^3.0.1",
    "koa-route": "^3.2.0",
    "koa-router": "^7.4.0",
    "koa-schema": "0.0.1",
    "koa-static": "^4.0.1",
    "log4js": "^6.1.0"
  },
  "devDependencies": {
    "apidoc": "^0.19.1",
    "jsdoc": "^3.6.3"
  }
}

• 運行的命令

// -i demos/test是測試文件所在的目錄
// -f ".*\\.js$" 是用來指定要生成api的文件格式的
// -o ./apidoc是用來指定生成文件的目錄的
 apidoc -i demos/test -f ".*\\.js$" -o ./apidoc

原因

在0.19.1版本中沒有zh-cn這個編碼了，得設置成爲zh_cn。
之所以會設置成爲這個錯誤的編碼是因爲在這篇博客中看到的教程設置的，現在版本迭代之後，zh-cn已經不能用了。
參見官方現有的locales

經驗教訓

• 能看官網教程的時候還是儘量看官網的，畢竟網上散落的教程有可能過時了，但是官網的總會是最新的。。
• 大家在博客中寫教程的時候，儘量帶上軟件的版本號信息，環境信息，不然容易誤導人