php接口文档.doc,怎么安装apidoc去编写PHP接口的web文档

apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档。

【安装】

apidoc是基于nodeJs平台，在安装apidoc之前，需要先安装nodeJs。

下面介绍一下Windows平台下nodeJs的安装。

【nodeJs安装】

首先，去[node.js官网]上下载最新的安装包，请下载自己对应系统的安装包。

下载完毕后，按照一般的软件安装步骤安装即可。

按照安装步骤安装完毕后，node环境也已经配置好了，现在来验证一下node是否已正确安装配置。

首先，打开Window Shell窗口。使用win+R快捷键打开运行窗口，在文本框中输入cmd并回车打开Windows Shell。

然后，在控制台输入node命令进入node控制台。

最后，运行一个Hello World程序。在node控制台中输入console.info("hello world");，如果输出如下图所示的结果，则表示node安装配置成功。

create-online-document-use-apidocnode-install-check.png

除了node之外，npm(node package manager，node安装包管理器)也是很重要的，可以通过它来便捷地下载和安装node应用。在Windows Shell中输入npm命令，如果出现如下图所示的信息，则表示npm也正确安装完毕。

create-online-document-use-apidocnpm-check.png

【apidoc安装】

apidoc可以利用npm来快速安装。

1、进入Windows Shell，输入npm install apidoc -g进行apidoc的安装，等待一定时间(根据自身的网速)的下载和安装之后，如果出现下图所示的信息，则表示apidoc安装成功。

2、在Windows Shell中输入apidoc -v命令，如果出现如下图所示的界面，则表示apidoc已安装成功。

create-online-document-use-apidocapidoc-install-check.png

【使用apidoc】

一个典型的文件目录结果如下图所示。

1505960105.jpg

其中：

apidoc.json：apidoc的项目级配置文件，它必须位于整个工程目录顶层。

1000.php：用于演示的demo源文件，它可以位于整个工程目录的顶层目录及其子目录下。apidoc会搜索整个工程目录选择所有可能的源文件。

apidoc.json包含的代码如下：

1505960278(1).jpg

包含的代码如下：

1505960241(1).jpg

下面通过这个demo来介绍如何生成文档文件。

首先，在Windows Shell中进入apidoc工程目录的上层目录。例如笔者的apidoc的工程位于E:\workspaces\sublime\apidoc 路径下。在这个目录中创建名为src的工程目录，将apidoc.json和1000.php文件置于src目录下。

create-online-document-use-apidoccd-into-apidoc-dir.png

然后，在Windows Shell中输入apidoc -i src/ -o apidoc/命令，如果出现如下图所示的Done结果，则表明文档已经生成，位于同级目录的apidoc(与-o apidoc对应)目录下。

create-online-document-use-apidocapidoc-demo1-generate.png

最后，打开apidoc目录，可以看到如下图所示的静态Web文件。双击index.html就可以在浏览器中打开生成在线接口文档网站。

1505960647(1).jpg

配置

apidoc.json文件是项目级的配置文件，接下来简单地介绍一下其中常用的配置项。

name 工程名。如果该字段不存在，则apidoc会尝试通过package.json(apidoc顶层配置文件)来生成

version 工程文档的版本号。如果该字段不存在，则apidoc会尝试通过package.json(apidoc顶层配置文件)来生成

description 工程详细描述。如果该字段不存在，则apidoc会尝试通过package.json(apidoc顶层配置文件)来生成

title 文档标题，显示在文档界面的最上方

url 整个api url的前缀，接下来的所有接口url都会加上这个前缀

sampleUrl api示例的url前缀。如果设置了这个值，则界面中显示请求表单，可以用于测试接口

title 文档头(header)的连接锚点名

filename 文档头所使用的文件

footer 文档尾(footer)的连接锚点名

filename 文档尾所使用的文件

order 接口的排列顺序list，如果不指定，则由apidoc自行确定

一个比较完整的配置文件如下：

1505960779(1).jpg