apidoc是什么窗怒？
apidoc 是一個(gè)根據(jù)源代碼中api注解創(chuàng)建api文檔的工具映跟，輕便易用蓄拣。
問題背景
- 現(xiàn)象：nodejs中使用apidoc在控制臺(tái)報(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)
頁(yè)面顯示為空白:
錯(cuò)誤截圖
- 軟件環(huán)境：
- apidoc 版本：0.19.1
- 操作系統(tǒng) macOS 10.14.6
- Google chrome 版本 79.0.3945.117（正式版本）
- node v10.16.3
- 測(cè)試源代碼
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 用戶注冊(cè)
* @apiDescription 用戶注冊(cè)
* @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是測(cè)試文件所在的目錄
// -f ".*\\.js$" 是用來(lái)指定要生成api的文件格式的
// -o ./apidoc是用來(lái)指定生成文件的目錄的
apidoc -i demos/test -f ".*\\.js$" -o ./apidoc
原因
在0.19.1版本中沒有zh-cn這個(gè)編碼了，得設(shè)置成為zh_cn努隙。
之所以會(huì)設(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)的總會(huì)是最新的躬存。张惹。
- 大家在博客中寫教程的時(shí)候，盡量帶上軟件的版本號(hào)信息岭洲，環(huán)境信息宛逗，不然容易誤導(dǎo)人
