zoukankan      html  css  js  c++  java
  • 使用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文件修改成如上的默认状态,重新生成即可完成

  • 相关阅读:
    GDOI模拟赛Round 1
    Codeforces 241B
    Codeforces 325E
    Codeforces 235E
    Codeforces 293B
    Codeforces 263E
    快速傅里叶变换FFT
    后缀自动机
    NOI2011 Day2
    NOI2014 Day2
  • 原文地址:https://www.cnblogs.com/imsoft/p/6766967.html
Copyright © 2011-2022 走看看