使用apidoc工具来给项目做接口文档，不仅有合理的源码注释，还可以生成对应的文档。是给源码写备注的一个极佳实践。

---

工具名称：apiDoc 

Git地址： 

项目地址： 

样例项目： 

博客学习：

出现的问题：

 

1. 运行：apidoc -i test/ -o apidoc/，

　问题：提示 warn: Please create an apidoc.json configuration file.

　解决：在项目源码文件夹创建 apidoc.json 文件

{  "name": "测试",  "version": "0.0.1",  "description": "API文档测试",  "title": "API文档测试",  "url" : "http://xxxxxxx",  "sampleUrl" : "http://xxxxxxxx",  "template":{    "forceLanguage":"zh-cn"  }}

 

2. 运行：apidoc -i test/ -o apidoc/，

　问题：提示如下错误

Block: 2,Element: '@apiParam',Source: '@apiParam {Number} 当前分页.' Block: 3, Element: '@apiSuccess', Source: '@apiSuccess {String} 新增博文页面.'

　说明：@apiParam、@apiSuccess 等注解后面需要加上结果

　　　　使用规范：@apiSuccess [(group)] [{

type}] field [description]

　解决：在文字前面加上与 field “返回字段的名称” 对应的结果，没有结果时写 null 即可。

 

3. 运行：apidoc -i test/ -o apidoc/ 没有报错，得到结果

　问题：打开的界面只有loading，没有显示内容

　说明：在查找很多相关内容之后，有可能的结果是说配置文件中的version需要和apidoc对应，结果删除了也不行。后面把配置文件修改成最初状态，正常导出API文档。

　解决：将apidoc.json文件修改成如上的默认状态，重新生成即可完成