丢掉word，用apidoc来写文档

 

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，就可以让需要文档的小伙伴们访问了。