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
经验教训
- 能看官网教程的时候还是尽量看官网的，毕竟网上散落的教程有可能过时了，但是官网的总会是最新的。。
- 大家在博客中写教程的时候，尽量带上软件的版本号信息，环境信息，不然容易误导人
