Web API文档生成工具apidoc

api
留言

在项目开发过程中，总会牵扯到接口文档的设计与编写，如果使用office工具，写一个文档，总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具，so来介绍一下apidoc！

apidoc可以根据代码注释生成web api文档，支持大部分主流语言java javascript php coffeescript erlang perl python ruby go…，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。

apidoc从注释生成静态html网页文档，不仅支持项目版本号，还支持api版本号。

安装

主页: http://apidocjs.com
github: https://github.com/apidoc/apidoc
可以使用npm install apidoc -g进行安装。
如果不想使用全局命令，可以使用下面的构建工具：

应用

在命令行窗口执行apidoc -h命令，可以查看帮助。
下面讲讲常用的方法

1
2
3
4
5
6
7
8
// 典型用法
apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"

-i 表示输入，后面是文件夹路径
-o 表示输出，后面是文件夹路径
默认会带上-c，在当前路径下寻找配置文件(apidoc.json)，如果找不到则会在package.json中寻找 "apidoc": { }
-f 为文件过滤，后面是正则表达式，示例为只选着js文件
与-f类似，还有一个 -e 的选项，表示要排除的文件/文件夹，也是使用正则表达式

配置文件（apidoc.json）

apidoc.json示例：

1
2
3
4
5
6
7
{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

如果放入package.json中，相同的字段可以直接使用package.json的定义，额外的字段放入apidoc下

1
2
3
4
5
6
7
8
9
{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}

注释写法

常用关键字 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
@api {method} path [title]
  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单
  method可以有空格，如{POST GET}
@apiGroup name
  分组名称，被解析为导航栏菜单
@apiName name
  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
@apiDescription text
  接口描述，支持html语法
@apiVersion verison
  接口版本，major.minor.patch的形式
  
@apiIgnore [hint]
  apidoc会忽略使用@apiIgnore标注的接口，hint为描述
@apiSampleRequest url
  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种

@apiDefine name [title] [description]
  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块
  在@apiDefine内部不可以使用@apiUse
@apiUse name
  引入一个@apiDefine的注释块

@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
  用法基本类似，分别描述请求参数、头部，响应错误和成功
  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  用法完全一致，但是type表示的是example的语言类型
  example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)
  
@apiPermission name
  name必须独一无二，描述@api的访问权限，如admin/anyone

文档生成后的结果是这样的：
http://apidocjs.com/example/