⽤apidoc⽣成在线html⽂档
在开发接⼝的过程中，需要向外发布相应的接⼝⽂档。开始的时候使⽤word来写⽂档，时间长了发现有⼏个问题。1) 编写不⽅便。每次新增借⼝的时候都要复制上⼀个接⼝，然后再进⾏修改，⼀些相同的部分⽆法复⽤，接⼝多了⽂档会变的很长，还经常需要调整格式。2) 发布不⽅便。⽂档更新时，需要发给需要的⼩伙伴。即使⽤git来进⾏管理，虽然拉取⽐较⽅便，但由于⽂件格式的问题，也不⽅便⽐较两次提交的差异。
由于有这些问题，决定寻⼀种更优雅有效的⽅式来编写⽂档。经过⽐较，发现了，可以⽐较好的解决上⾯提到的问题。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 ⽂档
编写完成后，运⾏
apidocIn 表⽰GetUser.java ⽂件的存放⽬录，apidocOut 表⽰希望apidoc ⽂档⽣成的⽬录。运⾏成功后，在输  出⽬录可以看见⼀堆⽣成的⽂件，其中index.html 是我们需要的⽂档。在浏览器打开就可以看见效果了。效果如下图所⽰：
注意：apidocIn 和apidocOut 不是命令，⽽是java
⽂件的存放⽬录，和⽂档⽣成后的⽬录。
后⾯可以配置⼀下nginx ，指定访问的路径映射到index.html ，就可以让需要⽂档的⼩伙伴们访问了。Shell 代码
1. apidoc -i apidocIn -o apidocOut

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。