apidoc是什么？

apidoc 是一個(gè)根據(jù)源代碼中api注解創(chuàng)建api文檔的工具，輕便易用。

問題背景

• 現(xiàn)象：nodejs中使用apidoc在控制臺報(bào)如下錯(cuò)誤：

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)

頁面顯示為空白:

錯(cuò)誤截圖

• 軟件環(huán)境：
  • apidoc 版本：0.19.1
  • 操作系統(tǒng) 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在瀏覽器中的標(biāo)題",
    "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"
  }
}

• 運(yùn)行的命令

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

原因

在0.19.1版本中沒有zh-cn這個(gè)編碼了，得設(shè)置成為zh_cn。
之所以會設(shè)置成為這個(gè)錯(cuò)誤的編碼是因?yàn)樵?a target="_blank">這篇博客中看到的教程設(shè)置的，現(xiàn)在版本迭代之后，zh-cn已經(jīng)不能用了。
參見官方現(xiàn)有的locales

經(jīng)驗(yàn)教訓(xùn)

• 能看官網(wǎng)教程的時(shí)候還是盡量看官網(wǎng)的，畢竟網(wǎng)上散落的教程有可能過時(shí)了，但是官網(wǎng)的總會是最新的。。
• 大家在博客中寫教程的時(shí)候，盡量帶上軟件的版本號信息，環(huán)境信息，不然容易誤導(dǎo)人