apidoc之apidoc.josn配置页眉和页脚路径问题

apidoc是非常好用的文档生成工具,有时候多个项目需要生成文档时就要多个配置,用-c命令载入配置,比如-c project1


配置apidoc.json(在project1目录下面有footer.md和header.md):

{
  "name": "接口文档",
  "version": "1.0.0",
  "description": "文档描述",
  "title": "接口",
  "url" : "http://xxxxx.com/",
  "header": {
    "title": "接口通用规则",
    "filename": "header.md"
  },
  "footer": {
    "title": "API 状态码说明",
    "filename": "footer.md"
  }
}

生成文档:

apidoc -c project1/ -i api/ -t tpl/ -o doc/

上面会报错(命令):

{"message":"Can not read: header.md","level":"error"}

提示找不到这个文件

在生成命令加入--debug调试:

apidoc -c project1/ -i api/ -t tpl/ -o doc/ --debug

输出:

{"message":"Error: Can not read: header.md.header\n    at C:\\马赛克g\\npm\\node_modules\\apidoc\\lib\\package_info.js:181:23

大概知道问题在哪个目录提示的了,进入package_info.js调试一下(用Can not read大概定位在哪里):

PackageInfo.prototype._getHeaderFooter = function(json) {
    var result = {};
    var self = this;

    ['header', 'footer'].forEach(function(key) {
        if (json[key] && json[key].filename) {
//            var filename = path.join(app.options.src, json[key].filename);
            var dir = self._resolveSrcPath();
            var filename = path.join(dir, json[key].filename);
			console.log('文件路径',filename);//打印路径

            if ( ! fs.existsSync(filename))
                filename = path.join('./', json[key].filename);

            try {
                app.log.debug('read header file: ' + filename);
                var content = fs.readFileSync(filename, 'utf8');
                result[key] = {
                    title  : json[key].title,
                    content: app.markdownParser ? app.markdownParser.render(content) : content
                };
            } catch (e) {
                throw new Error('Can not read: ' + filename + '.'+key);
            }
        }
    });

    return result;
};

再次执行生成命令后得到上面的调试:

打印路径 api\header.md

知道问题了,apidoc.json配置里面是相对api文件所在路径的,所以修改配置文件的路径即可,最终:

{
  "name": "接口文档",
  "version": "1.0.0",
  "description": "文档描述",
  "title": "接口",
  "url" : "http://xxxxx.com/",
  "header": {
    "title": "接口通用规则",
    "filename": "../project1/header.md"
  },
  "footer": {
    "title": "API 状态码说明",
    "filename": "../project1/footer.md"
  }
}

再次运行:

apidoc -c project1/ -i api/ -t tpl/ -o doc/

成功啦,一一对应咯。

评论/留言