使用apidoc 生成Restful web Api文档——新手问题与解决方法

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

---

工具名称：apiDoc 
Git地址：https://github.com/apidoc/apidoc 
项目地址：http://apidocjs.com/ 
样例项目：http://apidocjs.com/example_basic/ 

博客学习：http://blog.csdn.net/soslinken/article/details/50468896

出现的问题：
 

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文件修改成如上的默认状态，重新生成即可完成