使用apidoc 生成Restful web Api文档——新手问题与解决方法-阿里云开发者社区

开发者社区> 开发与运维> 正文

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

简介: 使用apidoc工具来给项目做接口文档,不仅有合理的源码注释,还可以生成对应的文档。是给源码写备注的一个极佳实践。 工具名称:apiDoc Git地址:https://github.com/apidoc/apidoc 项目地址:http://apidocjs.

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

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章