一：介绍

apidoc 是一个基于 nodejs 的 API 文档生成工具，从代码注释中提取特定格式的内容，生成 API 文档。程序员都不喜欢写文档，但是程序员习惯写注释。可谓一举两得。

apidoc目前支持php,python,java,go,rust,perl,c#等等几乎主流语言都支持。

二：安装

1：首先安装nodejs

下载地址：https://nodejs.org/en/download/

安装完成后，查看一下：

2：全局安装 apidoc

npm  install apidoc -g

3：查看是否安装成功

apidoc -v

三：小试身手

1：新建一个项目目录abc：E:\www\abc，在该目录下新建3个文件

（1）：apidoc.json

{
  "name": "测试API",
  "version": "1.0.0",
  "description": "测试API",
  "title": "测试API",
   "url" : "https://127.0.0.1:90/v1",
  "header": {
    "title": "测试APId",
    "filename": "header.md"
  },
  "footer": {
    "title": "测试API",
    "filename": "footer.md"
  }
}

header

footer

2：在abc目录下新建一个src目录，该目录保存程序

3：src下新建两个文件，执行的时候apidoc从这两个文件提取

（1）：articles.php

<?php

/**
 * @api {get} /articles/:id 根据单个id获取文章信息
 * @apiName 根据id获取文章信息
 * @apiGroup Articles
 *
 * @apiParam (params) {String} id       文章id
 *
 * @apiSuccess {Array} article 返回相应id的文章信息
 *
 * @apiSuccessExample Success-Response:
 *    HTTP/1.1 200 OK
 *      {
 *        "tile": "文章标题2",
 *        "date": 1483941498230,
 *        "author": "classlfz",
 *        "content": "文章的详细内容"
 *       }
 *
 * @apiError (Error 4xx) 404 对应id的文章信息不存在
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 对应id的文章信息不存在
 *     {
 *       "error": err
 *     }
 */

（2）：user.php

<?php


/**
 * @api {post} /user/ 查询用户
 * @apiName 根据查询条件返回用户信息
 * @apiGroup User

 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

4：运行，首先进入abc目录

apidoc -i src/ -o apidoc/

这样表示成功，打开看下

直接浏览器打开apiddoc中的index.html。

然后把nginx或者apache绑定到这个目录即可！

参数说明:
-f 文件类型
-i 文件输入路径(必选)
- o 输出路径(必选)
- t 使用模板(非必选，一般不用)

apidoc -f .php -i src/ -o apidoc/

这句话意思是：把src目录下的.php文件 api输出到apidoc目录下（运行该命令，需要在apidoc.json同级目录下）

三：基本规则：

以下转自：https://www.jianshu.com/p/a799c23234b8

/** 
 * @api {method} path [title]
 */

/**
 * @apiGroup name
 */

/**
 * @apiName name
 */

/**
 * @apiParam [(group)] [{type}] [field=defaultValue] [description]
 */

/**
 * @apiParamExample [{type}] [title]
 *    example
 */

/**
 * @apiSuccess [(group)] [{type}] field [description]
 */

/**
 * @apiSuccessExample [{type}] [title] example
 */