文档生成工具 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文档即可。