Node.js ApiDoc 工具手册中文译本

以下内容，均为官方文档的中文译稿，如在学习过程中发现有误，请不吝赐教，指正修改。

1. DEMO

访问站点：http://apidocjs.com/#demo

查看演示效果。

2. 入门

2.1 前言

文档中所有的示例都使用了Javadoc风格（也可使用C#、Go、Dart、Java、JavaScript、PHP、TypeScript以及其他支持Javadoc的语言）：

/**
* This is a comment.
*/

对于其他语言使用其他特定的多行注释代码：

• CoffeeScript

###
This is a comment.
###

• Elixir

@apidoc """
This is a comment.
"""

• Erlang(%在注释中是可选的)

%{
   
% This is a comment.
%}

• Perl(Doxygen)

#**
# This is a comment.
#*

• Python

"""
This is a comment.
"""

• Ruby

=begin
This is a comment.
=end

• Lua

--[[
This is a comment.
--]]

2.2 安装

这里很简单就是利用npm进行安装，详细安装过程在上面讲过：

npm install apidoc -g

2.3 运行

apidoc -i myapp/ -o apidoc/ -t mytemplate/

将目录myapp里的文件，使用目录mytemplate目录下的模板文件来生成的apidoc文档最后存储在目录apidoc下。

如果不指定参数，apiDoc会根据当前目录下全部的.cs、.dart、.erl、.go、.java、.js、.php、.py、.rb、.ts文件来生成文档到当前目录的doc目录下。

2.4 命令行

通过命令行参数查看帮助信息：

apidoc -h

重要参数讲解：

2.5 GRUNT模式

支持单独的grunt模式，参见：github.com/apidoc/grunt-apidoc

或者通过npm来安装：

npm install grunt-apidoc --save-dev

grunt是一套前端自动化工具，一个基于nodejs的命令行工具，一般用于：压缩文件、合并文件、简单语法检查。

关于grunt的可访问官方网站获取详细信息：https://gruntjs.com/

这里暂不做深入讨论。

2.6 模板

apiDoc包含一个默认的模板使用handlebars、Bootstrap、RequireJS和jQuery用于输出生成的api_data.js和api_project.js作为一个html页面。

默认情况下生成的apiDoc文档使用复杂的模板，支持：

• versioning：查看你的API接口不同版本

• compare：对比你的API接口在两个版本之间的变化

查看示例，这里我在官方演示demo里随便对比了一个版本差异效果如图：

创建属于自己的模板

当然你也可以创建一个你自己的模板来生成apiDoc文档的api_data.js、api_project.js或者仅json文件api_data.json、api_project.json。

查看模板的源代码：https://github.com/apidoc/apidoc/tree/master/template

2.7 扩展

apiDoc可以通过你自己的参数进行扩展（如果有一些是你不需要的）。以在apidoc/apidoc-core项目上的lib/parsers/、lib/workers和lib/filters/目录为例，parser分离参数数据，worker用所有找到的数据处理附件函数，filter减少数据需要的东西。

示例：

apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js

这要比请求整个项目创建来生成apiDoc要好。

2.8 配置文件（apidoc.json）

apidoc.json是可选的在你的项目根目录下，包含你项目的一些基本信息，比如标题、摘要、版本等，配置项像header/footer或者模板特定选项。

apidoc.json示例：

{
    "name": "apidoc-example",
    "version": "0.3.0",
    "description": "apiDoc example project",
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1",
    "header": {
        "title": "My own header title",
        "filename": "header.md"
    },
    "footer": {
        "title": "My own footer title",
        "filename": "footer.md"
    },
    "order": [
        "GetUser",
        "PostUser"
    ],
    "template": {
        "withCompare": true,
        "withGenerator": true
    }
}

如果你使用了package.json（eg：在node.js项目里），所有的apidos.json配置可以同样由package.json来完成，只需要把它们添加到"apidoc":{}参数下即可。

package.json示例：

{
    "name": "example",
    "version": "0.1.0",
    "description": "apiDoc basic example",
    "apidoc": {
        "title": "Custom apiDoc browser title",
        "url": "https://api.github.com/v1"
    }
}

apidoc.json的基本配置信息：

参数名	描述
name	项目名称，如果在apidoc.json中不存在此字段，apiDoc将会通过package.json中的值来命名
version	项目版本，如果在apidoc.json中不存在此字段，apiDoc将会通过package.json中的值来命名
description	项目描述，如果在apidoc.json中不存在此字段，apiDoc将会通过package.json中的值来命名
title	浏览器标题
url	api接口路径前缀（端点），eg：https://api.github.com/v1
sampleUrl	如果设置了，那么一个用于测试api方法（发送请求）将会可用。具体参见@apiSampleRequest获取更多细节
header
title	对于包含header.md文件的导航文本（参见：Header/Footer）
filename	对于包含header.md文件的文件名（markdown文件）
footer
title	对于包含footer.md文件的导航文本
filename	对于包含footer.md文件的文件名（markdown文件）
order	输出的api名称/组名称顺序列表。未定义的名称将自动显示在最后
	"order":["Error", "Define", "PostTitleAndError", "PostError"]

模板中的特殊配置

接下来的这些配置都是apiDoc默认模板里的特殊配置。

参数名	类型	描述
template
forceLanguage	String	禁用浏览器的语言自动检测并且设置特定的区域设置，例如：de、en，查看可用区域：here
withCompare	Boolean	允许与旧版本的API进行比较，默认值为：true
withGenerator	Boolean	在页脚输出生成器信息，默认值为：true
jQueryAjaxSetup	Object	设置Ajax请求的默认值

2.9 页眉/页脚

在你项目的apidoc.json配置文件中你可以增加页眉和页脚。

标题将会在导航中可见，文件名应该是markdown格式。

示例：

{
    "header": {
        "title": "My own header title",
        "filename": "header.md"
    },
    "footer": {
        "title": "My own footer title",
        "filename": "footer.md"
    }
}

3. 示例

一个小的演示介绍示例：speakerdeck.com

3.1 基本

在基本示例中我们有一个小的项目文件和一个apidoc.json配置文件。

演示效果就不截图了，大家访问这个地址查看即可：http://apidocjs.com/example_basic/

apidoc.json

完整的代码：

{
    "name": "example-basic",
    "version": "0.1.0",
    "description": "apiDoc basic example",
    "template": {
        "withCompare": false
    }
}

通过apidoc.jsonapiDoc获取到你项目的名称、版本、描述信息，这个文件是可选的，它取决于你的模板里是否要求有这些数据。

example.js

完整的代码：

/*
 * Basic Example
 *
 * This is a basic