先声明下，apidoc是基于注释来生成文档的，它不基于任何框架，而且支持大多数编程语言，为了springboot系列的完整性，所以标了个题。

一、apidoc简介

apidoc通过在你代码的注释来生成api文档的。它对代码没有侵入性，只需要你写好相关的注释即可，并且它仅通过写简单的配置就可以生成高颜值的api接口页面。它基于node.js，所以你需要安装node.js环境。node.js安装，点击这里。这里就不介绍。

二、准备工作

安装完node.js安装api.doc,它的项目源码：https://github.com/apidoc/apidoc 。

通过命令安装：

npm install apidoc -g

三、注释怎么写

• @api

@api {method} path [title]
method：请求方法，
path：请求路径 
title(可选)：标题

• @apiDescription

@apiDescription text
text说明

• @apiError

@apiError [(group)] [{type}] field [description]
（group）（可选）：参数将以这个名称分组，不设置的话，默认是Error 4xx 
{type}（可选）：返回值类型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]} 
field：返回值字段名称 
descriptionoptional（可选）：返回值字段说明

• @apiGroup

@apiGroup name

name：组名称，也是导航的标题

更多注释，参见官方文档：http://apidocjs.com/#params

四、写给栗子

首先写配置文件

在项目的主目录新建一个apidoc.json文件：

{
 "name": "example",
 "version": "0.1.0",
 "description": "A basic apiDoc example"
}

更多配置参考：http://apidocjs.com/#configuration

写个注释:

/**

* @api {POST} /register 注册用户

* @apiGroup Users

* @apiVersion 0.0.1

* @apiDescription 用于注册用户

* @apiParam {String} account 用户账户名

* @apiParam {String} password 密码

* @apiParam {String} mobile 手机号

* @apiParam {int} vip=0 是否注册Vip身份 0 普通用户 1 Vip用户

* @apiParam {String} [recommend] 邀请码

* @apiParamExample {json} 请求样例：

* ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=

* @apiSuccess (200) {String} msg 信息

* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误

* @apiSuccessExample {json} 返回样例:

* {"code":"0","msg":"注册成功"}

*/

用apidoc命令生成文档界面

先cd到工程的外层目录，并在外层目建个输出文档的目录，我建的是docapi。

输命令：

apidoc -i chapter4/ -o apidoc/

-i 输入目录 -o 输出目录

chapter4是我的工程名。

可以看到在apidoc目录生成了很多文件:

打开index.html,可以看到文档页面:

服务端开发过程中，我们需要提供一份 API 接口文档给 Web 端和移动端使用。实现 API 接口文档编写工作，有很多种方式，例如通过 Word 文档编写，或者通过 MediaWiki 进行维护。此外，还有比较流行的方式是利用 Swagger 自动化生成文档。这里，笔者想分享另一个 Web API 文档生成工具 apidoc。

apidoc 是通过源码中的注释来生成 Web API 文档。因此，apidoc 对现有代码可以做到无侵入性。此外，apidoc 可以支持多种语言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby，Lua。通过 apidoc 可以非常方便地生成可交互地文档页面。

开始入门

首先，我们需要 node.js 的支持。在搭建好 node.js 环境后，通过终端输入 npm 命名进行安装。

npm install apidoc -g

接着，我们还需要添加 apidoc.json 文件到项目工程的根目录下。

这里，笔者主要演示 Java 注释如何和 apidoc 结合使用。现在，我们先来看一个案例。

最后，我们在终端输入 apidoc 命令进行文档生成。这里，我们用自己的项目工程的根目录替代 myapp/,用需要生成文档的地址替代 apidoc/。

apidoc -i myapp/ -o apidoc/

例如，笔者的配置是这样的。

apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/

代码注释

@api

@api 标签是必填的，只有使用 @api 标签的注释块才会被解析生成文档内容。格式如下：

@api {method} path [title]

这里，有必要对参数内容进行讲解。

@apiDescription

@apiDescription 对 API 接口进行描述。格式如下：

@apiDescription text

@apiGroup

@apiGroup 表示分组名称，它会被解析成一级导航栏菜单。格式如下：

@apiGroup name

@apiName

@apiName 表示接口名称。注意的是，在同一个 @apiGroup 下，名称相同的 @api 通过 @apiVersion 区分，否者后面 @api 会覆盖前面定义的 @api。格式如下：

@apiName name

@apiVersion

@apiVersion 表示接口的版本，和 @apiName 一起使用。格式如下：

@apiVersion version

@apiParam

@apiParam 定义 API 接口需要的请求参数。格式如下：

这里，有必要对参数内容进行讲解。

类似的用法，还有 @apiHeader 定义 API 接口需要的请求头，@apiSuccess 定义 API 接口需要的响应成功，@apiError 定义了 API 接口需要的响应错误。

这里，我们看一个案例。

此外，还有 @apiParamExample，@apiHeaderExample， @apiErrorExample，@apiSuccessExample 可以用来在文档中提供相关示例。

@apiPermission

@apiPermission 定义 API 接口需要的权限点。格式如下：

@apiPermission name

此外，还有一些特别的注解。例如 @apiDeprecated 表示这个 API 接口已经废弃，@apiIgnore 表示忽略这个接口的解析。关于更多的使用细节，可以阅读官方文档：http://apidocjs.com/#demo

完整的案例

最后，我们用官方的案例，讲解下一个完整的配置。

首先，配置 apidoc.json，内容如下：

接着，我们配置相关的 Java 源码注释。

然后，执行命名生成文档。

生成的页面，如下所示。

（完）

pidoc可以根据规定的格式的代码注释生成api接口静态html网页文档说明文档，大部分主流语言java javascript php coffeescript erlang perl python ruby等，对于多个团队开发来说，非常有帮助。

下载包安装

https://nodejs.org/dist/v4.4.4/

配置path（注意解压路径）

注意目录(/tmp/node-v4.4.4-linux-x64)

配置/etc/profile文件：

export NODE_HOME=/tmp/node-v4.4.4-linux-x64

export PATH=$PATH:$NODE_HOME/bin

export NODE_PATH=$NODE_HOME/lib/node_modules

注：配置全局环境，如果在/etc/profile中配置，那么需要每次登陆后source一下，如果想长久有效，请在/etc/bashrc中配置

验证安装

node -v

npm -v

全局安装apidoc

npm install apidoc -g

验证安装

apidoc -v

配置apidoc.json

{

"name": "WayBill 接口文档",

"version": "1.0.0",

"description": "接口模块，向其他模块提供数据的访问",

"title": "xxxxx模块1.0接口",

"private": true,

"sampleUrl": " "

}

apidoc文档注释规范（见官网）

http://apidocjs.com/

执行生成命令

apidoc -i app/Http/Controllers -o public/doc

参考文档：

http://apidocjs.com/

https://github.com/apidoc/apidoc