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

1. 介绍apidoc的基本概念
2. 安装、使用和简单配置
3. 一些特殊参数的含义及其使用
4. 介绍一些使用经验

前言

apidoc能做什么

apidoc是一个轻量级的在线REST接口文档生成系统，可以根据其特定的规则的代码注释来生成静态网页。首先看下它生成的文档界面和风格。

支持

apidoc支持多种主流的编码语言，包括Java、C、C#、PHP和Javascript。一般情况下，语言会有多种注释方法，例如就Java中有普通风格的多行注释和Javadoc风格的注释。apidoc并不支持所有的注释，譬如Java仅中支持Javadoc风格的注释。首先要说明的是，apidoc并不具备语义识别能力，它不会发现代码中是否有BUG，它仅仅通过文件后缀来判断语言类型。下面是一些不同语言注释示例：

安装

apidoc是基于nodeJs平台，在安装apidoc之前，需要先安装nodeJs。关于nodeJs的安装，一搜一大把，不过为了文章的完整性，还是首先介绍一下Windows平台下nodeJs的安装。

nodeJs安装

首先，去node.js官网上下载最新的安装包，请下载自己对应系统的安装包。譬如笔者的操作系统是64位Windows操作系统，就下载下图所示的node安装包。

下载完毕后，按照一般的软件安装步骤安装即可。由于笔者的计算机已经安装过了，在这里就不过细演示了。

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

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

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

最后，运行一个Hello World程序。在node控制台中输入

console.info("hello world");

如果输出如下图所示的结果，则表示node安装配置成功。

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

npm

apidoc安装

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

1、进入Windows Shell，输入npm install apidoc -g进行apidoc的安装，如下图。

npm install apidoc -g

等待一定时间（根据自身的网速）的下载和安装之后，如果出现下图所示的信息，则表示apidoc安装成功。

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

apidoc -v

初步使用

下面通过一些简单的demo来介绍如何利用apidoc生成一份在线接口文档。

命令行

在正式开始之前，先介绍一下apidoc中的重要命令和参数。apidoc的命令格式如下：

apidoc 参数

一些重要的参数如下表所示：

apidoc -i demo/ -o apidoc/ # 可以通过搜索demo目录中的文件快速的生成文档文件，并将这些文件放在apidoc目录下。

apidoc -h # 显示帮助信息

使用apidoc

新建文件夹demo

创建apidoc.json文件和test.php文件

apidoc.json:

{

  "name": "****",

  "title": "****API",

  "description":"****API接口文档",

  "url" : "http://api.demo.com",

  "version": "0.1.0"

}

test.php文件

<?php

/**

 *

 * @api {get} /user/{id}

 * @apiDescription 获取用户信息接口描述

* @apiGroup User

 * @apiName getUserInfo

 * @apiParam {Number} id 用户ID

 * @apiVersion 0.1.0

 *

 *

 * @apiExample {curl} 访问示例：

* curl -i http://api.demo.com/user/4711

*

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

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

 */

function GetUser($id){}

进入demo目录，

运行命令  apidoc

如果自定义文件后缀名：md，可用命令：apidoc -f  ".*\.md$"

在该目录下会生成doc目录，直接访问index.html即可

又例如：在WWW目录下，在youbo目录创建apidoc.json文件和test.php文件，把apidoc文件生成在apidoc/youbo/文件夹下

执行bat自动生成文档，新建test.bat，加入以下内容。路径需自行修改

cmd /k "cd /d D:\phpStudy\PHPTutorial\WWW & apidoc -i youbo -o apidoc/youbo/"

配置

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

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

{

    "name": "demo",

    "version": "1.0.0",

    "description": "这是一个简单的apidoc的demo",

    "title": "demo",

    "url": "https://api.github.com/v1",

    "sampleUrl": "https://api.github.com/v1/test",

    "header": {

        "title": "header",

        "filename": "header.md"

    },

    "footer": {

        "title": "footer",

        "filename": "footer.md"

    },

    "order": [

        "Error",

        "Define",

        "PostTitleAndError",

        "PostError"

    ]

}

更多的配置项请参考apidoc官方文档站点。

Params

apidoc中最核心的东西就是参数（params）的书写，本节介绍apidoc中一些重要的params。

@api

@api定义一个特定的接口。如果一个注释块既不包含@apiDefine又没有包含@api参数，则apidoc会直接忽略这个注释块。这个参数在界面上表示一个接口区域块如下:

@api的书写格式为：

@api {method} path [title]

注意，[xxx]表示一个可选的参数，下同。

下表介绍了@api中的参数含义。

更多的配置项请参考apidoc官方文档站点。

@apiDefine

@apiDefine表示定义一个变量，该变量可以指代任意值（字符串、参数块），这个参数并且写在独立的代码块中。可以使用@apiUse来使用其定义的变量。

@apiDefine的书写格式为：

@apiDefine name [title] [description]

下表介绍了@apiDefine中的参数含义。

下面的代码定义一个错误块，然后在接口定义中引用使用这个错误块。多个不同接口可以引用同样的@apiDefine块，这也变成语言的变量功能一直。可以消除重复代码。

/**

 * @apiDefine MyError

 * @apiError UserNotFound The <code>id</code> of the User was not found.

 */

/**

 * @api {get} /user/:id

 * @apiUse MyError

 */

@apiDescription

用于@api代码块中，用于详尽地描述接口的功能。

@apiDescription的书写格式为：

@apiDescription text

text就是具体的描述内容，可以直接使用Markdown语法，这极大地丰富了其表现形式。

@apiGroup

表示接口所属的组，最直接的体现就是在侧边导航中将接口分在对用的组中。

@apiGroup的书写格式为：

@apiGroup name

name表示组名，可以是任意字符串。值得注意的是，name不支持中文，一旦输入中文，apidoc就会忽略这些中文字符。如果需要在界面中显示中文接口组名，只需要使用@apiDefine定义一个中文字符串，然后name用变量名替换即可。

/**

 * @apiDefine group 测试

 */

/**

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

 * @apiName GetUser

 * @apiGroup group

 */

@apiName

表示接口的名字，应该在每个@api块中使用。可以生成一个Web锚点，快速定位接口位置。可以看到锚点（url的#后面的字符串）通常由groupName-apiName构成。

@apiName的书写格式为：

@apiName name

@apiUse

表示引用一个@apiDefine定义的值或块，相当于直接替换变量的值。

@apiUse的书写格式为：

@apiUse name 

name是一个已定义的@apiDefine中的name，如果输入的name不存在，则会抛出类似下面的异常信息。

{ File: 'doem\\test.php',

  Block: 4,

  Element: '@apiUse',

  Groupname: 'test',

  Definition: '@apiUse group',

  Example: '@apiDefine MyValidGroup Some title\n@apiUse MyValidGroup' }

下面是一个示例：

/**

 * @apiDefine test

 * @apiParam {Number} id Users unique ID.

 */

/**

 * @apiUse test

 * @apiParam {Number} name name.

 */

@apiParam

表示一个请求参数。

@apiParam的书写格式为：

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

下表介绍了@apiParam中的参数含义。

下面是一个简单的示例：

/**

 * @api {get} /user/:id

 * @apiParam {Number} id Users unique ID.

 */

/**

 * @api {post} /user/

 * @apiParam {String} [firstname]  用户名（非必填）.

 * @apiParam {String} lastname     用户姓（必填）.

 */

@apiSuccess

表示请求成功时的一个返回字段。

@apiSuccess的书写格式为：

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

@apiSuccess的参数含义与@apiParam一致，这里就不再做说明了。

@apiError

表示请求失败时的一个返回字段。

@apiError的书写格式为：

@apiError [(group)] [{type}] field [description]

与apiSuccess的参数含义完全一致。

@apiParamExample

表示一个请求范例。

@apiParamExample的书写格式为：

@apiParamExample [{type}] [title] example

下面是一个简单的示例：

/**

 * @api {get} /user/:id

 * @apiParamExample {json} Request-Example:

 *     {

 *       "id": 4711

 *     }

 */

@apiSuccessExample

表示一个响应范例。其书写格式和参数含义与@apiParamExample完全一样。

@apiSampleRequest

表示一个接口测试块，可以根据定义的请求参数来生成一个表单，用来进行接口测试。

@apiSampleRequest的书写格式为：

@apiSampleRequest url

url可以与配置文件（apidoc.json）中的sampleUrl以及@api定义的path连接成一个完整的测试url。例如：

/**

 * @api {get} /user/:id

 * @apiParam {Number} id Users unique ID.

 * @apiSampleRequest /test

 */

生成的界面截图如下：

一些实际经验

下面介绍一下在实际使用过程发现的东西。

绝大部分地方可使用Markdown语法

在几乎所有的描述类字段处都可以使用符合Markdown语法的文本，可以使得文档形式更加美观。

/**

 * @api {get} /user/:id

 * @apiParam {String} rule

 *

 * - 规则1：不能使用小数

 * - 规则2：不能相加

 */

对象类型的参数

如果请求的参数是一个对象，那此时因为如果书写呢？比如需要Post一个Person对象，Person中包括name、age字段，那么可以这样书写。

/**

 * @api {post} /user

 * @apiName obj

 * @apiParam {Object} person

 * @apiParam {String} person.name  姓名

 * @apiParam {Integer} person.age 年龄

 */

从下图中可以看到name和age字段的前面有些缩进，而且字段显示名为name和age。