apidoc接口文档的快速生成

官方文档连接：http://apidocjs.com/#demo

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，它仅仅通过文件后缀来判断语言类型。下面是一些不同语言注释示例：

* Java、Javascript、PHP *

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

* Python *

"""
@api {get} /user/:id Request User information
@apiName GetUser
@apiGroup User

@apiParam {Number} id Users unique ID.

@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.
"""

安装

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也正确安装完毕。

apidoc安装

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

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