apidoc ----api文档生成工具的使用

apidoc 是一款api文档生成工具，简单易用。apidoc会生成一个html，建议同时配置在服务器上，例如通过Nginx配置静态资源，供多人协作浏览，配置好之后，每次修改了api，只需要一行命令即可完成文档更新。

一、安装

$npm install apidoc -g

二、配置（可选）

在项目目录下添加 apidoc.json 文件

ex：

{

	"name": "example", //项目名称

	"version": "0.1.0",

	"description": "apiDoc basic example",

	"title": "Custom apiDoc browser title",

	"url" : "https://api.github.com/v1" //一般为域名

}

三、基本格式

在相关文件内加入注释，ex：

/**

* @api {get} /user/:id Request User information

* @apiName GetUser

* @apiGroup User

* @apiPermission Web

* @apiParam {Number} id Users unique ID.

*

* @apiSuccess {String} firstname Firstname of the User.

* @apiSuccess {String} lastname  Lastname of the User.

* @apiSuccessExample Success-Response:

*    HTTP/1.1 200 OK

*    {

*      "firstname": "John",

*      "lastname": "Doe"

*    }

*/

三、基本命令

ex:

$ apidoc -i controller -o doc

controller : 输入目录，添加了上面的api注释的目录

-o : 文档输出目录

四、使用

打开doc目录下的index.html文件，即可看到刚刚生成的api文档。

demo

如果配置到服务器上，使用方法同理。