丢掉word,用apidoc来写文档

62 篇文章 1 订阅
30 篇文章 0 订阅

 

from : http://build.iteye.com/blog/2334273


在开发接口的过程中,需要向外发布相应的接口文档。开始的时候使用word来写文档,时间长了发现有几个问题。1) 编写不方便。每次新增借口的时候都要复制上一个接口,然后再进行修改,一些相同的部分无法复用,接口多了文档会变的很长,还经常需要调整格式。2) 发布不方便。文档更新时,需要发给需要的小伙伴。即使用git来进行管理,虽然拉取比较方便,但由于文件格式的问题,也不方便比较两次提交的差异。

 

      由于有这些问题,决定寻找一种更优雅有效的方式来编写文档。经过比较,发现了apidoc,可以比较好的解决上面提到的问题。apidoc采用了一种类似写代码注释的方式来写文档,支持编写多种语言的文档。最后生成的文档以网页的形式发布,方便快捷,便于阅读。下面就来简单介绍一下怎么使用apidoc来写文档。

 

     1.安装node

     由于apidoc依赖node.js的包管理工具npm进行安装,所以安装apidoc之前要先安装node.js(npm会在安装node时顺带进行安装)。具体的安装教程可以参考这里

 

    2.安装apidoc

    安装完了npm之后,就可以安装apidoc了。在命令行输入

Shell代码   收藏代码
  1. npm install apidoc -g  

     就可以进行安装了。安装完成输入

Shell代码   收藏代码
  1. apidoc -h  

    出现相关的提示帮助信息,说明安装成功了。

 

    3 apidoc 常用注解介绍

    apidoc是运用各个不同的注解来完成文档的写作的。学习apidoc,主要就是学习注解的用法。apidoc和命名行的命令很像,由一个注解关键字加一些选项构成。下面介绍一下apidoc主要的注解。

Apidoc代码   收藏代码
  1. @api {method} path [title]  
    这是apidoc必需的注解,用来说明api的方法,访问路径和作用。
Apidoc代码   收藏代码
  1. @apiParam [(group)] [{type}] [field=defaultValue] [description]  
      这个注解用来说明api请求参数的类型,大小和作用。
Apidoc代码   收藏代码
  1. @apiSuccess [(group)] [{type}] field [description]  

    这个注解说明api返回参数的类型,大小和作用。

    关于注解的详细用法可以访问官网,上面有详细的用法和示例。

 

     4.编写apidoc文档

    了解了关于注解的用法之后,就可以用注解来编写文档了。例如我们可以编写一个GetUser.java文件。里面的内容如下所示:

Java代码   收藏代码
  1. /** 
  2.  * @api {get} /user/:id Request User information 
  3.  * @apiGroup User 
  4.  * 
  5.  * @apiParam {Number} id Users unique ID. 
  6.  * 
  7.  * @apiSuccess {String} firstname Firstname of the User. 
  8.  * @apiSuccess {String} lastname  Lastname of the User. 
  9.  */  

 

    5 生成apidoc文档

    编写完成后,运行

Shell代码   收藏代码
  1. apidoc -i apidocIn -o apidocOut  

    apidocIn表示GetUser.java文件的存放目录,apidocOut表示希望apidoc文档生成的目录。运行成功后,在输   出目录可以看见一堆生成的文件,其中index.html是我们需要的文档。在浏览器打开就可以看见效果了。效果如下图所示:

    

     后面可以配置一下nginx,指定访问的路径映射到index.html,就可以让需要文档的小伙伴们访问了。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值