Api文档生成工具apiDoc

发表于 | 分类于

apiDoc简介

最近在写api,需要把接口整理出来给其他人使用,一贯操作就是一手word写起,懒症发作不想每次都写个word文档,于是就找到了此物的存在.

API文档生成还有许多其他工具,比如swagger,但是我不又不想写那么多东西,于是最终还是用了apiDoc.

apiDoc是通过源码中的注释来生成Web API文档.因此对代码没有侵入性,而且不需要写繁琐的语法.支持 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby，Lua.

安装

安装nodejs

安装apiDoc需要nodejs支持.

安装apiDoc

npm install apidoc -g

配置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" //api路径前缀
}

运行

1
2
3
4
apidoc -i myapp/ -o apidoc/ -t mytemplate/
# -i : 指定读取源文件的目录
# -o : 指定输出文档的目录
# -t : 指定模板文件一般不用管,除非自定义模板

apidoc注释的参数

@api

[必填字段] 否则apiDoc会忽略该条注释

@api {method} path [title]

例如

1
2
3
/**
* @api {get} /user/:id 获取用户信息
*/
参数 必填 描述
method yes DELETE,GET,POST,PUT…
path yes 请求路径
title no 接口标题

@apiDescription

对API接口进行描述

@apiDescription text

@apiGroup

表示分组名称,导出的文档会以组的形式作为导航,不支持中文

@apiGroup name

@apiHeader

描述接口请求头部需要的参数(功能类似@apiParam)

1
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
参数 必填 描述
(group) no 所有的参数都会以该参数值进行分组(默认Parameter)
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field yes 参数名称(定义该头部参数为必填)
[field] yes 参数名称(定义该头部参数为可选)
=defaultValue no 参数默认值
description no 参数描述 
1
2
3
4
/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiHeaderExample

请求头部示例

1
2
@apiHeaderExample [{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

忽略改接口,不会被解析,主要用在如果某个接口未完成,不想生成在文档里,就在注释最前端加入这个参数

1
@apiIgnore [hint]
1
2
3
4
/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

@apiName

接口名称，每一个接口注释里都应该添加该字段，在导出的接口文档里会已该字段值作为导航子标题，如果两个接口的@apiVersion和@apiName一样，那么有一个接口的注释将会被覆盖(接口文档里不会展示)

@apiName name

1
2
3
4
/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

@apiParam

接口请求体参数

1
@apiParam [(group)] [{type}] [field=defaultValue] [description]
参数 必填 描述
(group) no 所有的参数都会以该参数值进行分组(默认Parameter)
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
{type{size}} no 返回类型,同时定义参数的范围 {string{..5}}意为字符串长度不超过5 {string{2..5}}意为字符串长度介于25之间
{number{100-999}}意为数值介于100999之间
{type=allowedValues} no 参数可选值 {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 yes 参数名称(定义该请求体参数为必填)
[field] yes 参数名称(定义该请求体参数为可选)
=defaultValue no 参数默认值
description no 参数描述

例如:

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 no 请求内容格式
title no 请求示例标题
example yes 请求示例详情(兼容多行) 
1
2
3
4
5
6
7
/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

@apiPremission

允许访问该接口的角色

1
@apiPermission name

@apiSampleRequest

设置了该参数后，导出的html接口文档中会包含模拟接口请求的form表单；如果在配置文件apidoc.json中设置了参数sampleUrl,那么导出的文档中每一个接口都会包含模拟接口请求的form表单，如果既设置了sampleUrl参数，同时也不希望当前这个接口不包含模拟接口请求的form表单，可以使用@apiSampleRequest off来关闭

参数 必填 描述
url yes 模拟接口请求的url @apiSampleRequest http://www.example.com意为覆盖apidoc.json中的sampleUrl参数 @apiSampleRequest off意为关闭接口测试功能

例：
发送测试请求到:http://api.github.com/user/:id

1
2
3
4
Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 */

发送测试请求到:http://test.github.com/some_path/user/:id(覆盖apidoc.json中的sampleUrl参数)

1
2
3
4
5
Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

关闭接口测试功能

1
2
3
4
5
Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest off
 */

发送测试请求到http://api.github.com/some_path/user/:id(由于没有设置apidoc.json中的sampleUrl参数，所以只有当前接口有模拟测试功能)

1
2
3
4
5
Configuration parameter sampleUrl is not set
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiDefine

类似于定义常量,通过@apiDefine一出定义,便可在其他注释模块中使用.一般将可复用的定义,比如错误代码,错误提示等.最后在文档导出时会自动替换所引用的注释模块，定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本)

1
2
@apiDefine name [title] 
	[description]
1
2
3
4
5
6
7
8
9
/**
 * @apiDefine MyError MyError Description
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

/**
 * @api {get} /user/:id
 * @apiUse MyError
 */
参数 必填 描述
name yes 注释模块名称(唯一)，不同@apiVersion可以定义相同名称的注释模块
title no 注释模块标题
Description no 模块详细描述(另起一行，可包含多行)

@apiError

接口错误返回

1
@apiError [(group)] [{type}] field [description]
参数 必填 描述
(group) no 所有的参数都会通过这个参数进行分组，如果未设置，默认值为Error 4xx
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field yes 返回id
description no 描述 
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 no 响应类型
title no 示例标题
example yes 示例详情(可多行) 
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

接口示例,通@apiErrorExample

@apiDeprecated`

标注一个借口已经废弃

@apiDeprecated [text]

1
2
3
4
5
6
/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

@apiSuucess

接口成功返回参数

1
@apiSuccess [(group)] [{type}] field [description]
参数 必填 描述
(group) no 所有的参数都会以该参数值进行分组,默认值:Success 200
{type} no 返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field yes 返回值(返回成功码)
=defaultValue no 参数默认值
description no 参数描述

例:

1
2
3
4
5
/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

包含(group):

1
2
3
4
5
/**
 * @api {get} /user/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

返回参数中有对象:

1
2
3
4
5
6
7
/**
 * @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.
 */

返回参数中有数组：

1
2
3
4
5
6
/**
 * @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 no 返回内容格式
title no 返回示例标题
example yes 返回示例详情(兼容多行)

例：

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

1
@apiUse name

引入注释模块，如果当前模块定义了@apiVersion,那么版本相同或版本最近的注释模块会被引入
参数列表:

参数 必填 描述
name yes 引入注释模块的名称

例:

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

1
@apiVersion version

定义接口/注释模块版本
参数列表:

参数 必填 描述
version yes 版本号(支持APR版本规则:major.minor.patch)

例:

1
2
3
4
/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */

参考官方文档