RESTful web API文档生成器

Posted on   |   In   |     |   visitors

问：开发业务模块代码最重要的是什么？
答：API接口文档

如果你是后台开发，是否会有以下困扰：

  • 开发API接口，还要通过wiki写接口文档，严重影响效率
  • 接口不是一次就能定下来的，后续可能还要维护，所以还需要去修改文档

如果你是前端工程师，是否有过下面的困扰：

  • 返回的数据怎么少字段，后台什么时候改了接口

我们总是吐槽文档不全，文档写的不好，然而却没有想到开发的同时顺便把文档也写了。这篇博文的重点就是为大家介绍一款生成RESTful web API文档的神器——apidoc，GitHub 4000多star。这款神器通过源代码中的注释生成最终的文档，所以需要按照规范编写注释。

安装和使用

前言

文中的例子全部使用Javadoc-Style编写，也可以在所有支持Javadoc的语言（如C#, Go, Dart, Java, JavaScript, PHP, TypeScript等）中使用。其他语言可以使用它们特定的多行注释。

1
2
3
/**
 * This is a comment.
 */

安装

1
npm install apidoc -g

使用

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

使用mytemplate/下的模板文件，为myapp/目录下的所有文件创建api文档，并保存在apidoc/目录下。如果不带任何参数，apiDoc为当前目录以及子目录下的所有.cs, .dart, .erl, .go, .java, .js, .php, .py, .rb, .ts文件创建文档，并保存在./doc/目录。

命令行参数

1
2
# 查看命令行参数
apidoc -h

列出部分重要参数：

参数描述示例
-f, –file-filters通过正则过滤出需要解析的文件（可以使用多个-f）。默认为.cs, .dart, .erl, .go, .java, .js, .php, .py, .rb, .ts。仅解析.js和.ts文件：
apidoc -f ".*\\.js$" -f ".*\\.ts$"
-i, –input源文件或项目目录apidoc -i myapp/
-o, –output存放生成的文档的目录apidoc -o apidoc/
-t, –template为生成的文档使用模板，也可以创建和使用自己的模板apidoc -t mytemplate/

Grunt模块

作者也为大家开发了一款grunt的打包工具http://github.com/apidoc/grunt-apidoc。

1
npm install grunt-apidoc --save-dev

模板

apiDoc默认模板：使用了handlebars，Bootstrap，RequireJS和jQuery为输出的api_data.js和api_project.js文件生成html页面。

apiDoc默认使用一个复杂的模板，支持如下功能：

  • 版本管理：查看不同版本的API
  • 比较：查看一个API的两个版本之间的区别

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

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

扩展

apiDoc也可以扩展自己的参数，具体细节请查看apidoc/apidoc-core项目的lib/parsers/, lib/workers/目录。

配置

apiDoc提供了两种配置方式，要么在工程根目录添加apidoc.json文件，要么在package.json中添加apidoc字段。

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

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"
  }
}

apidoc.json配置字段

字段描述
name工程名称。如果apidoc.json中不包含此字段，则由package.json确定
version工程版本号。如果apidoc.json中不包含此字段，则由package.json确定
description工程描述。如果apidoc.json中不包含此字段，则由package.json确定
title文档页面标题
urlapi前缀，如：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名和api分组名的顺序列表，未定义名称的api自动在后面展示。
"order": ["Error", "Define", "PostTitleAndError", "PostError"]

apiDoc默认模板特定的配置字段

字段类型描述
template
forceLanguageString禁用浏览器自动语言检测，并设置一个特定的语言。例如：de, en。可选语言
withCompareBoolean开启与旧版本API比较，默认true
withGeneratorBoolean在页尾输出生成信息，默认true
jQueryAjaxSetupObject为Ajax请求设置默认参数

在apidoc.json添加header和footer。

1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  }
}

示例

继承

你可以将文档中多次使用的部分放到一个定义中。如下：

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
39
40
41
42
43
44
45
46
/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
/**
 * @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"
 *     }
 *
 * @apiUse UserNotFoundError
 */
/**
 * @api {put} /user/ Modify User information
 * @apiName PutUser
 * @apiGroup User
 *
 * @apiParam {Number} id          Users unique ID.
 * @apiParam {String} [firstname] Firstname of the User.
 * @apiParam {String} [lastname]  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 * @apiUse UserNotFoundError
 */

继承只能包含一层，多层级将会降低行内代码的可读性，增加复杂度。

版本控制

保存之前定义的文档块，用于不同版本的接口比较，因此前端开发很容易看到哪些地方有变化。

在修改接口文档之前，将历史文档块复制到文件_apidoc.js。

所以在每个文档块设置@apiVersion非常重要。

apiDoc参数

结构体参数@apiDefine用于将文档块定义为可复用的整体，并且可以包含在api文档块中。

除了其它定义块，一个定义的块中可以包含所有的参数（如@apiParam）。

@api

必须包含这个标记，否则apiDoc将会忽略文档块。定义块@apiDefine不需要@api。

1
@api {method} path [title]
字段描述
method请求方法名：DELETE, GET, POST, PUT, …。更多信息请查看Wikipedia HTTP请求方法
path请求路径
title 可选用于导航的简称
1
2
3
/**
 * @api {get} /user/:id
 */

@apiDefine

定义一个通用块或者权限块，每个块中只能有一个@apiDefine，使用@apiUse导入通用块。

1
2
@apiDefine name [title]
    [description]
字段描述
name块或值的唯一名称
title 可选简称，只用在命名函数中，如@apiPermission和@apiParam(name)
description 可选下一行开始的详细说明，可以多行，仅用在命名函数，如@apiPermission
1
2
3
4
5
6
7
8
9
/**
 * @apiDefine MyError
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */
/**
 * @api {get} /user/:id
 * @apiUse MyError
 */
1
2
3
4
5
6
7
8
9
/**
 * @apiDefine admin User access only
 * This optional description belong to to the group admin.
 */
/**
 * @api {get} /user/:id
 * @apiPermission admin
 */

@apiDeprecated

标记废弃的API

1
@apiDeprecated [text]
字段描述
text多行文本
1
2
3
4
5
6
7
8
9
/**
 * @apiDeprecated */
/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

@apiDescription

API的详细描述

1
@apiDescription text
字段描述
text多行描述文本
1
2
3
4
5
6
/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

返回的错误参数

1
@apiError [(group)] [{type}] field [description]
字段描述
(group) 可选所有参数按这个名称分组，如果未设置此字段，默认为Error 4xx，可以使用@apiDefine设置标题和描述
{type} 可选返回类型，例如：{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组）等
field返回的标识符
description字段描述
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

@apiErrorExample

返回的错误示例，输出为格式化的代码

1
2
@apiErrorExample [{type}] [title]
    example
字段描述
type 可选响应格式
title 可选示例简称
example详细示例，支持多行文本
1
2
3
4
5
6
7
8
/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 * HTTP/1.1 404 Not Found
 * {
 *   "error": "UserNotFound"
 * }
 */

@apiExample

API的使用示例，输出为格式化的代码

1
2
@apiExample [{type}] title
    example
字段描述
type 可选代码语言
title示例简称
example详细示例，支持多行文本
1
2
3
4
5
/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 * curl -i http://localhost/user/4711
 */

@apiGroup

应该一直使用，定义API文档块所属的分组。分组用于生成输出中的主导航，结构定义不需要@apiGroup

1
@apiGroup name
字段描述
name分组名称，也用作导航名称
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiGroup User
 */

@apiHeader

描述传递给API的请求头，类似@apiParam，只不过输出文档在参数之上。

1
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
字段描述
(group) 可选所有参数按此名称分组，如果未设置，默认为Parameter，你也可以在@apiDefine中定义名称和描述
{type} 可选参数类型，例如：{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组）等
field变量名
[field]带括号标识此参数可选
=defaultValue 可选参数默认值
描述 可选字段描述
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiHeaderExample

请求头参数示例

1
2
@apiHeaderExample [{type}] [title]
    example
字段描述
type 可选请求格式
title 可选示例简称
example详细示例，支持多行文本
1
2
3
4
5
6
7
/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 * {
 *   "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 * }
 */

@apiIgnore

@apiIgnore块不会被解析，如果你在源代码中留下过期或者未完成的api，并且不想将其发布到文档中，这个标识符非常有用。

将其放在块的顶部

1
@apiIgnore [hint]
字段描述
hint 可选忽略原因的简短信息
1
2
3
4
/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

@apiName

应该永远使用，定义API文档块的名称，名称将用于生成输出文档中的子导航。结构定义不需要@apiName

1
@apiName name
字段描述
nameAPI的唯一名称，可以为不同的@apiVersion定义相同的名称
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

@apiParam

定义传递给API的参数

1
@apiParam [(group)] [{type}] [field=defultValue] [description]
字段描述
(group) 可选所有参数按此名称分组，默认为Parameter，也可以在@apiDefine中定义名称和描述
{type} 可选参数类型，例如：{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组）等
{type{size}} 可选变量大小信息
{string{..5}} 最多5个字符的字符串
{string{2..5}} 最少2个字符，最多5个字符的字符串
{Number{100-999}} 介于100和999之间的数字
{type=allowedValues} 可选变量允许的值
{string="small"} 只能包含”small”的字符串
{string="small","huge"} 包含”small”或”huge”的字符串
{number=1,2,3,99} 允许为1,2,3,99中的一个值
{string {..5}="small","huge"} 最多5个字符的字符串，并且只能包含”small”和”huge”
field参数名
[field]带括号标识此参数可选
=defaultValue 可选参数默认值
description 可选参数描述
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */
/**
 * @api {post} /user/
 * @apiParam {String} [firstname] Optional Firstname of the User.
 * @apiParam {String} lastname Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18] Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *        In generated documentation a separate
 *        "Login" Block will be generated.
 */

@apiParamExample

请求参数示例

1
2
@apiParamExample [{type}] [title]
    example
字段描述
type 可选请求格式
title 可选示例简称
example详细示例，支持多行文本
1
2
3
4
5
6
7
/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 * {
 *   "id": 4711
 * }
 */

@apiPermission

权限名称，如果用@apiDefine定义名称，生成的文档将会包含额外的名称和描述

1
@apiPermission name
字段描述
name权限唯一的名称
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiPermission none
 */

@apiSampleRequest

此参数配合apidoc.json配置中的sampleUrl参数使用，如果配置了sampleUrl，所有API方法都将有api测试表单，并追加在@api结束位置。如果未配置sampleUrl，仅包含@apiSampleRequest的方法有测试表单。
如果在方法块中配置了@apiSampleRequest url，这个url作为请求地址（当它以http开头，会覆盖sampleUrl）
如果配置了sampleUrl，并且想在指定方法不包含测试表单，可以在文档块中配置@apiSampleRequest off。

1
@apiSampleRequest url
字段描述
url测试api服务地址
@apiSampleRequest http://www.example.com
@apiSampleRequest /my_test_path
@apiSampleRequest off
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
// Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 */
// Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */
// Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest /test
 */
// Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest off
 */
// Configuration parameter sampleUrl is not set
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiSuccess

成功返回的参数

1
@apiSuccess [(group)] [{type}] field [description]
字段描述
(group) 可选所有参数按此名称分组，默认为Success 200，可以在@apiDefine中定义名称和描述
{type} 可选返回类型，例如：{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组）等
field返回标识字段
description 可选字段描述
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
/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname Lastname of the User.
 */
// 带(group)示例
/**
 * @api {get} /user/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname Lastname of the User.
 */
// 带对象示例
/**
 * @api {get} /user/:id
 * @apiSuccess {Boolean} active Specify if the account is active.
 * @apiSuccess {Object} profile User profile information.
 * @apiSuccess {Number} profile.age Users age.
 * @apiSuccess {String} profile.image Avatar-Image.
 */
// 带数组示例
/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles List of user profiles.
 * @apiSuccess {Number} profiles.age Users age.
 * @apiSuccess {String} profiles.image Avatar-Image.
 */

@apiSuccessExample

成功响应的信息，按格式化代码输出

1
2
@apiSuccessExample [{type}] [title]
    example
字段描述
type 可选响应格式
title 可选示例简称
example详细示例，支持多行文本
1
2
3
4
5
6
7
8
9
/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 * HTTP/1.1 200 OK
 * {
 *   "firstname": "John",
 *   "lastname": "Doe"
 * }
 */

@apiUse

包含一个@apiDefine定义的块。如果与@apiVersion一起使用，将包含相同的或最近的一个

1
@apiUse name
字段描述
name定义块的名称
1
2
3
4
5
6
7
8
9
10
/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */
/**
 * @api {get} /user/:id
 * @apiUse MySuccess
 */

@apiVersion

配置文档块的版本，也可以在@apiDefine中使用，具有相同组和名称的API，可以在生成的文档中比较不同的版本，因此你或前端开发人员可以回溯自上一个版本以来API中的更改

1
@apiVersion version
字段描述
version支持简单的版本控制（主版本号.次版本号.补丁号）。更多信息请参考http://semver.org/
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */

到此为止，你应该对apidoc熟悉了一大半了吧！其实作为开发者，一定要养成写注释、写文档的习惯，也是程序员进阶的必要条件。

谨以此文鞭策自己。

Enjoy it? Donate me!您的支持将鼓励我继续创作！

热评文章