需要安装的环境（本篇依次介绍）

在这里插入图片描述
电脑一台
nodejs环境
npm环境
apidoc环境
安装nodejs和npm
进入官网 https://nodejs.org/en/ 下载首页推荐的版本就可以 本篇这里选择了8.12.0 (不建议10以上)

node.png
下载完成后打开安装程序，一直next到底 。

安装完成之后 使用cmd进行查看nodejs版本

node -v
v8.12.0
说明安装成功,安装nodejs的同时，一并会把npm也替我们安装好，同样使用cmd查看npm版本

npm -v
v6.4.1
安装完成~

如果提示(成功则跳过此步骤)

node 不是内部或者外部命令，也不是可运行的程序或批处理文件
我们需要配置一下环境变量

以win7为例, 右键我的电脑 → 高级系统设置 → 高级 → 环境变量 → 系统变量Path的变量值末尾追加

;C:\Program Files\nodejs
完整路径如下(仅供参考nodejs环境配置格式)

C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0;C:\Program Files (x86)\NVIDIA Corporation\PhysX\Common;C:\Program Files\nodejs
保存，之后再上方的 用户变量新建

变量名: Path

变量值: C:\Users\Administrator\AppData\Roaming\npm

env.png
安装apidoc
使用npm进行安装

npm install apidoc -g
npm install apidoc -g

npm WARN deprecated nomnom@1.8.1: Package no longer supported. Contact support@n
pmjs.com for more info.
C:\Users\Administrator\AppData\Roaming\npm\apidoc -> C:\Users\Administrator\AppD
ata\Roaming\npm\node_modules\apidoc\bin\apidoc

• apidoc@0.17.6
  added 42 packages from 25 contributors in 12.658s

使用

apidoc -h
可以查看帮助 说明安装成功

使用apidoc (PHP项目为例)
新建一个项目或者在老项目根目录创建 apidoc.json 文件（本篇新建的项目）

使用时候请去掉注释避免报错

apidoc.json

{
“name”: “appleFarm”, //文档项目名
“title”: “appleFarmAPI”, //html标题
“description”:“appleFarmAPI接口文档”, //文档描述
“url” : “https: //xxx.com”,//公共接口地址
“version”: “0.1.0” //文档版本
}
创建src目录,新建 test.php 文件
添加apidoc注释

test.php

class Home {
/**
* 定义一个变量 用于apiGroup 因为不支持直接输入中文
* @apiDefine test 测试
*/

    /*** @api {post} /Index/getVip 获取vip列表   页面加载时自动获取* @apiName GetUser* @apiGroup test** @apiParam {string} req1 请求值** @apiSuccess {String} res1 返回值1* @apiSuccessExample Success-Response:* {* 　　res1:"test"* }*/public function test(){....}

}
保存完毕之后 我们使用apidoc 命令进行生成文档(项目根路径下执行,也就是有apidoc.json文件的路径)

apidoc -i src/ -o apidoc/
info: Done.
该命令会把所有文件接口注释全部生成文档，放到apidoc目录下，我们进去点开index.html 就可以看到

result.png
至此，文档生成完毕。

apidoc相关的注释
@api {get} /users/:user_id Request User Information
最主要的参数，”{get}”定义了HTTP请求是GET，API地址是”/users/:user_id”，文档中API的名称是”Request User Information”。

@apiVersion 0.1.0
API的版本号，默认显示在API名称的右方。该参数可用来在不同的版本之间做比较，后面会介绍。

@apiName GetUser
API名称，不影响文档。

@apiGroup User
API分组名，文档内容中和菜单栏中同一组的API会在一同显示，方便阅读。

@apiPermission admin
API的访问权限，文档中默认会API地址下面显示。没有权限要求的话，此项可以省略。

@apiDescription API to get the user information.
API的详细描述，默认显示在API名称的下方。

@apiExample Example usage:
API调用示例，该参数的下一行就是示例的内容，直到有空行结束。可以定义多个@apiExample，默认在文档中会以标签形式列出，标签名就是”Example usage:”。

@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍，”{Number}”定义了字段类型，”user_id”是字段名称，后面则是字段描述。可以定义多个@apiParam字段。

@apiSuccess {String} name Name of the User.
API成功后返回的字段，如同@apiParam，”{String}”定义了字段类型，”name”是返回字段名称，后面则是字段描述。可以定义多个@apiSuccess字段。

@apiSuccessExample {json} Success-Response:
显示一个API成功返回后Response响应的示例，”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiSuccessExample，默认在文档中会以标签形式列出，标签名就是”Success-Response:”。

@apiError UserNotFound User was not found.
API发生错误后的返回，”UserNotFound”是错误名称，后面则是错误描述。可以定义多个错误返回。

@apiErrorExample {json} Error-Response:
显示一个API错误返回后Response响应的示例，”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiErrorExample，默认在文档中会以标签形式列出，标签名就是”Error-Response:”。

@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后，此参数即可省去，除非这个API的测试URL比较特殊，需特别指定。

作者：makisei
链接：https://www.jianshu.com/p/d324810d694d
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。