文档生成工具 APIDOC 笔记

文档生成工具 APIDOC 笔记

简介

代码即文档，代码注释生成文档是一种很好的文档方式。通过文档的时序化更新可以追溯整个工程的历史进程。团队的延续也需要良好的文档支持。我们团队使用的是APIDOC这种工具，该工具十分方便，上手快支持的语言多。

建议直接在文档所在目录进行命令行操作。

入门

1、安装命令

npm install apidoc -g

2、运行命令

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

apidoc 即工具 -i 即 输入文件路径 -o 输出文件路径 -t 我的模板

在没有任何参数的情况下，apiDoc 会提取出所有的 .cs .dart .erl .go .java .js .php .py .rb .ts格式的文件，并将其输出结果输出到 * ./doc/*中。

命令参数

1、帮助命令

apidoc -h

2、-f, –file-filters

使用这则表达式来选择文件进行处理。默认包括.cs .dart .erl .go .java .js .php .py .rb .ts。

代码示例：

下面代码只负责解析js和ts文件

apidoc -f ".*\\.js$" -f ".*\\.ts$"

3、-i, –input

输入 /文件目录名  。也就是你的工程的位置

代码示例：

apidoc -i myapp/

4、-o, –output

输出文件名。 也就是你想把文档输出出来的地方。

代码示例：

apidoc -o apidoc/

5、-t, –template

使用的输出模板。可以自己进行定义。

代码示例：

apidoc -t mytemplate/

模板

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

默认的模板比较复杂支持,支持:

- 版本 ： 支持不同版本的API的展示

- 比较 ： 支持两个不同版本API的展示

自由创建模板

你可以自己创建你的模板，使用apiDoc生成文件api_data.js, api_project.js或者api_data.json, api_project.json。

扩展

APIDOC可以进行扩展，但是不需要所以不翻译了。

配置(apidoc.json)

apidoc.json为项目基本文件，在项目的根目录负责存储所有与项目有关的基本信息。例如：标题、描述、版本、配置等问题。

apidoc.json简单示例

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

如果你用了package.json那么apidoc.json的参数只需要放到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 : 你的工程名。 （注释1）

version : 你的工程版本。 （注释1）

description : 介绍你的工程的描述（注释1）

title : 文档标题

url : 里面API的URL前缀。例如https://api.github.com/v1

sampleUrl : 如果设置了，一个测试用的表单将会可见。参考@apiSampleRequest获得更多信息。

header :

- title 在header.md文件中的导航信息

- filename header.md文件的文件名

footer

- title 在footer.md文件中的导航信息

- filename footer.md文件的文件名.

header.md 和 footer.md 中存储的就是抬头和结尾存储的内容。示例如下图所示。



order 一个表名了api-names和group-names关系的列表。没有定义的项最后显示。

"order": [
"Error",
"Define",
"PostTitleAndError",
"PostError"
]

注释：

1 如果apidoc.json不存在那么就回去寻找package.json.

模板配置信息

forceLanguage 字符串类型 禁用浏览器自动判断，制定一个语言。

例如 de, en

withCompare 布尔型 启用与旧的版本的比较。

默认 true

withGenerator 布尔型 在页脚输出生成信息 。

默认 true

jQueryAjaxSetup 对象 给Ajax请求设置默认的值。

API注释，举个栗子

/**

* @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.

*

* @apiSuccessExample Success-Response:

*     HTTP/1.1 200 OK

*     {

*       "firstname": "John",

*       "lastname": "Doe"

*     }

*

* @apiError UserNotFound The id of the User was not found.

*

* @apiErrorExample Error-Response:

*     HTTP/1.1 404 Not Found

*     {

*       "error": "UserNotFound"

*     }

*/

前面对于APIDOC的是用哪个已经基本入门，之后需要的参数，参照API文档即可。