Apidoc使用说明

Apidoc 使用说明

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

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

一、前言

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的安装
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安装配置成功。

apidoc安装
apidoc可以利用npm来快速安装。
1、进入Windows Shell，输入npm install apidoc -g进行apidoc的安装，如下图。

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

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

三、apidoc的使用

下面通过一些简单的demo来介绍如何利用apidoc生成一份在线接口文档。
命令行
在正式开始之前，先介绍一下apidoc中的重要命令和参数。apidoc的命令格式如下：
apidoc 参数
一些重要的参数如下表所示：
参数 描述
-f 选择要解析的文件，支持正则表达式。-f参数可以使用多次，多个表达式可以对应不同的-f。如：apidoc -f “.*.js