apiDoc教程目录

1、安装nodejs

2、安装apiDoc

3、创建apiDoc配置文件

4、在程序中使用apiDoc进行注释

apiDoc参数目录

@apiDefine

@apiDeprecated

@apiDescription

@apiError

@apiErrorExample

@apiExample

@apiGroup

@apiHeader

@apiHeaderExample

@apiIgnore

@apiName

@apiParam

@apiParamExample

@apiPermission

@apiPrivate

@apiSampleRequest

@apiSuccess

@apiSuccessExample

@apiUse

@apiVersion

5、@apiGroup兼容中文解决方法

6、apiDoc兼容Ajax json格式请求提交解决方法

7、生成API文档

市面上常用的API文档管理方式有apiDoc、Swagger2、DocClear。

Swagger2有一个比较明显的缺点：代码侵入，开启注解时会影响原本的系统性能。

同样DocClear也有一个比较明显的缺点：DocClear本身只是一个接口信息管理平台，所有的接口信息需要开发人员在平台内进行录入。

apiDoc作为API文档工具是一款通过源代码中的API注释创建文档，支持Java、JS、PHP、Tython等语言，没有Swagger2那样代码侵入，而是通过apiDoc的程序对我们的源代码文件进行扫描，获取文件内的apiDoc注释信息来创建API文档，进而生成静态的API文档页面。接下来就从头到尾给大家讲解一下apiDoc如何使用。

1、安装nodejs

具体请看这篇文章：node.js安装| 解决npm下载慢 | npm在项目开发中常用命令 | dependencies与devDependencies的区别 | npm build 打包配置

2、安装apiDoc

安装配置好nodejs后，在命令行界面输入：

npm install apidoc -g

3、创建apiDoc配置文件

在你的项目根目录下新建apidoc.json文件，该文件描述了项目对外提供接口的概要信息如名称、版本、描述、文档打开时浏览器显示标题和接口缺省访问地址。

实例文件：

{"name": "api-doc","version": "0.1.0","description": "接口文档描述","title": "接口文档标题","url" : "http://127.0.0.1:8091","sampleUrl" : "http://127.0.0.1:8091","order": ["系统","用户","角色","部门",],"template": {"forceLanguage": "zh_cn"}}

注：1、apidoc.json文件不是必须创建在项目中，而是为了方便操作。

2、若没有配置sampleUrl参数，apiDoc最终生成的API文档内将没有测试api方法。

以下是参数说明

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

模板特定设置

以下设置特定于apiDoc的默认模板。

4、在程序中使用apiDoc进行注释

这里已Java代码为例：

先给一个代码示例，Java项目中无需添加任意依赖，只需要按照apiDoc规定的方式进行注释即可，换句话说就是把原本JavaDoc的注释形式转化为apiDoc的注释形式即可。

/**     * @api {post} /urlDemo 示例接口名称     * @apiGroup 系统     * @apiVersion 0.0.1     * @apiDescription 示例接口描述     * @apiParam {String} param1 请求参数1     * @apiParam {Object} param2 请求参数2（JSON数据）     * @apiParam {String} param2.name 请求参数3（属于请求参数2的一个属性）     * @apiParam {Number} [param4] 请求参数4     * @apiUse ResponseBody     * @apiSuccess {Object} data响应数据描述     *     * @apiError _SESSION_EXPIRED 会话已过期     * @apiErrorExample {json} _SESSION_EXPIRED     *      HTTP/1.1 200 OK     *     {     *       "resultCode": -13,     *       "resultMsg": "会话已过期",     *       data: null     *     }     * @apiUse ResponseBody     */@PostMapping(value = "/urlDemo")public void urlDemo (@RequestBody Map<String, String> params){// ..}

apiDoc参数目录

@api
@apiDefine
@apiDeprecated
@apiDescription
@apiError
@apiErrorExample
@apiExample
@apiGroup
@apiHeader
@apiHeaderExample
@apiIgnore
@apiName
@apiParam
@apiParamExample
@apiPermission
@apiPrivate
@apiSampleRequest
@apiSuccess
@apiSuccessExample
@apiUse
@apiVersion

@apiDefine

@apiDefine name [title][description]

定义要嵌入到文档块中@api或api函数之类的文档文档块@apiPermission。

@apiDefine 每个方块只能使用一次

通过使用@apiUse已定义的块，将导入该块，或使用名称和标题和说明。

用法： @apiDefine MyError

例：

/** * @apiDefine MyError * @apiError UserNotFound The <code>id</code> of the User was not found. *//** * @api {get} /user/:id * @apiUse MyError */

/** * @apiDefine admin User access only * This optional description belong to to the group admin. *//** * @api {get} /user/:id * @apiPermission admin */

@apiDeprecated

@apiDeprecated [text]

将API方法标记为不推荐使用

用法： @apiDeprecated use now (#Group:Name).

例：

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

@apiDescription

@apiDescription text

API方法的详细说明。

用法： @apiDescription This is the Description.

例：

/** * @apiDescription This is the Description. * It is multiline capable. * * Last line of Description. */

@apiError

@apiError [(group)] [{type}] field [description]

错误返回参数。

用法： @apiError UserNotFound

例：

/*** @api {get} /user/:id* @apiError UserNotFound The <code>id</code> of the User was not found.*/

@apiErrorExample

@apiErrorExample [{type}] [title]example

错误返回消息的示例，以预格式化的代码输出。

用法： @apiErrorExample {json} Error-Response:
This is an example.

例：

/*** @api {get} /user/:id* @apiErrorExample {json} Error-Response:*     HTTP/1.1 404 Not Found*     {*       "error": "UserNotFound"*     }*/

@apiExample

@apiExample [{type}] titleexample

API方法使用示例。输出为预格式化的代码。

在端点描述的开头将其用作完整示例。

用法： @apiExample {js} Example usage:
This is an example.

例：

/*** @api {get} /user/:id* @apiExample {curl} Example usage:*     curl -i http://localhost/user/4711 */

@apiGroup

@apiGroup name

应该始终使用。

定义方法文档块属于哪个组。组将用于生成的输出中的主导航。不需要结构定义@apiGroup。

用法： @apiGroup User

例：

/*** @api {get} /user/:id* @apiGroup User*/

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

描述传递给您的API标头的参数，例如用于授权。

与@apiParam类似的操作，仅输出在参数之上。

用法： @apiHeader (MyHeaderGroup) {String} authorization Authorization value.

例子：

/** * @api {get} /user/:id * @apiHeader {String} access-key Users unique access-key. */

@apiHeaderExample

@apiHeaderExample [{type}] [title]example

参数请求示例。

用法： @apiHeaderExample {json} Request-Example:
{ "content": "This is an example content" }

例：

/*** @api {get} /user/:id* @apiHeaderExample {json} Header-Example:*     {*       "Accept-Encoding": "Accept-Encoding: gzip, deflate"*     }*/

@apiIgnore

@apiIgnore [hint]

将其放在一个块的顶部。

@apiIgnore不会解析的块。如果您在源代码中留下了过时的方法或未完成的方法，并且不想将其发布到文档中，则这很有用。

用法： @apiIgnore Not finished Method

例：

/*** @apiIgnore Not finished Method* @api {get} /user/:id*/

@apiName

@apiName name

应该始终使用。

定义方法文档块的名称。名称将用于生成的输出中的子导航。不需要结构定义@apiName。

用法： @apiName GetUser

例：

/*** @api {get} /user/:id* @apiName GetUser*/

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述传递给您的API方法的参数。

用法： @apiParam (MyGroup) {Number} id Users unique ID.

对于嵌套参数，请使用方括号符号（[]）。

例子：

/** * @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. * * @apiParam {Object} [address]         Optional nested address object. * @apiParam {String} [address[street]] Optional street and number. * @apiParam {String} [address[zip]]    Optional zip code. * @apiParam {String} [address[city]]   Optional city. */

@apiParamExample

@apiParamExample [{type}] [title]example

参数请求示例。

用法： @apiParamExample {json} Request-Example:
{ "content": "This is an example content" }

例：

/*** @api {get} /user/:id* @apiParamExample {json} Request-Example:*     {*       "id": 4711*     }*/

@apiPermission

@apiPermission name

输出权限名称。如果名称是@apiDefine在生成的文档中定义的，则包括其他标题和描述。

用法： @apiPermission admin

例：

/*** @api {get} /user/:id* @apiPermission none*/

@apiPrivate

@apiPrivate

将API定义为私有的，以允许创建两个API规范文档：一个排除私有API，而包括私有API。

用法： @apiPrivate

命令行用法来排除/包括私有API： --private false|true

例：

/*** @api {get} /user/:id* @apiPrivate*/

@apiSampleRequest

@apiSampleRequest url

将此参数与apidoc.json配置参数sampleUrl结合使用。

如果sampleUrl设置为，则所有方法都将具有api测试表单（将附加@api的端点）。
如果不使用sampleUrl，则只有的方法@apiSampleRequest将具有形式。

如果@apiSampleRequest url在方法块中设置了if ，则此url将用于请求（当它以http开头时，它将覆盖sampleUrl）。

如果sampleUrl设置为if 并且您不想要带有测试表单的方法，则将其添加@apiSampleRequest off到documentation块中。

用法： @apiSampleRequest http://test.github.com

例子：

这会将api请求发送到http://api.github.com/user/:id

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

这会将api请求发送到http://test.github.com/some_path/user/:id。
它将覆盖sampleUrl。

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

这会将api请求发送到http://api.github.com/test/user/:id。
它扩展了sampleUrl。

Configuration parameter sampleUrl: "http://api.github.com"/*** @api {get} /user/:id* @apiSampleRequest /test*/

这将禁用此api方法的api请求。

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

这会将api请求发送到http://api.github.com/some_path/user/:id
，因为未设置sampleUrl，所以仅激活此方法的请求。

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

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

成功返回参数。

用法： @apiSuccess {String} firstname Firstname of the User.

例：

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

的示例(group)，@apiSuccess更多组示例：

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

@apiSuccessExample [{type}] [title]example

成功返回消息的示例，以预格式化的代码输出。

用法： @apiSuccessExample {json} Success-Response:
{ "content": "This is an example content" }

例：

/*** @api {get} /user/:id* @apiSuccessExample {json} Success-Response:*     HTTP/1.1 200 OK*     {*       "firstname": "John",*       "lastname": "Doe"*     }*/

@apiUse

@apiUse name

包括一个带有@apiDefine定义的块。如果与@apiVersion相同或最接近的前任产品一起使用，则将包括在内。

用法： @apiUse MySuccess

例：

/** * @apiDefine MySuccess * @apiSuccess {string} firstname The users firstname. * @apiSuccess {number} age The users age. *//** * @api {get} /user/:id * @apiUse MySuccess */

@apiVersion

@apiVersion version

设置文档块的版本。版本也可以在中使用@apiDefine。

具有相同组和名称但不同版本的块可以在生成的输出中进行比较，因此您或前端开发人员可以追溯自上一个版本以来API中的更改。

用法： @apiVersion 1.6.2

例：

/*** @api {get} /user/:id* @apiVersion 1.6.2*/

5、@apiGroup兼容中文解决方法

apiDoc的@apiGroup是默认不支持中文需要我们单独处理一下：

1.找到安装目录中api_group.js
centos安装目录：/usr/lib/node_modules/apidoc/node_modules/apidoc-core/lib/workers/api_group.js
window安装目录：C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers\api_group.js
2.注释代码
将83行的替换代码注释：
//group = group.replace(/[^\w]/g, '_');

6、apiDoc兼容Ajax json格式请求提交解决方法

1.找到安装目录中的send_sample_request.js
[前缀参考前文]\apidoc\template\utils
2.将96行的ajax form表单的提交请求，替换成下面的这个：
      // send AJAX request, catch success or error callback
      $.ajax({
        url: url,
        dataType: "json",
        contentType: "application/json",
        data: JSON.stringify(param),
        headers: header,
        type: type.toUpperCase(),
        success: displaySuccess,
        error: displayError
      });

7、生成API文档

在第三节创建的apiDoc.json的目录位置打开命令行窗口，执行：

apidoc -i [项目完整路径] -o apidoc/

例如：

apidoc -i G:/Project/demo/ -o apidoc/

参数说明：

在项目中某些目录不需要扫描，API生成，则需要使用-e参数

例如：

apidoc -i G:/Project/demo/ -o apidoc/  -e web

命令执行成功后，将会输出：

{"message":"Done.","level":"info"}

此时我们可以在当前目录下看到，多了一个apidoc的文件夹，这个文件就是apiDoc生成的API文档。

打开文件夹可以看到类似如下内容：

此时我们打开index.html就可以看到我们通过在接口上添加的注释所生成的API文档了。

打开网页，可以看到如下内容：

通过网页内容，我们可以看到页面内有接口接口名称、接口描述、请求类型、接口参数说明、接口成功响应内容、接口异常内容、测试接口入口等内容。

这时我们就可以很方便的进行API查阅和测试了。

注：如果接口发生变化，只需要修改对应的代码注释再次通过命令进行API文档生成即可。

参考文档：apiDoc官网

转载来源：apiDoc教程（从入门到精通版、开发者API文档利器、全网最全讲解）。