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
更多的配置项请参考apidoc官方文档站点。
网友评论