apidoc生成Web API接口文档

1、apiDoc的安装与卸载

安装node.js

由于apidoc依赖node.js的包管理工具npm进行安装，所以安装apidoc之前要先安装node.js

安装apiDoc，dos命令执行：

npm install apidoc -g

卸载apiDoc，dos命令执行：

npm uninstall -g apidoc

2、apiDoc的使用（官网网址： https://apidocjs.com）

创建配置文件

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

{
    "name": "小程序接口文档", // 这里填写文档的名称
    "version": "0.0.1", // 这里填写文档的版本
    "description": "这里提供了本站所有使用到的接口的详细说明", // 这里填写文档的描述
    "title": "小程序接口文档", // 这里填写浏览器的标题
    "url": "https://127.0.0.1/xiaochengxu/api/" // 这里填写api的路径前缀
}

apidoc是运用各个不同的注释参数来完成文档的，常用注释参数（更多参考：官网网址： https://apidocjs.com）：

注释参数	描述
@api {method} path [title]	必填字段，否则，apidoc会忽略该条注释
@apiIgnore [原因描述]	放到注释块的最前面，该注释模块将不会被解析
@apiName name	接口名称
@apiDescription [text]	api接口的详细描述
@apiGroup name	定义接口所属的接口组
@apiDeprecated [text]	标注一个接口已经被弃用
@apiParam [(group)] [{type}] [field=defaultValue] [description]	接口请求体参数
@apiHeader [(group)] [{type}] [field=defaultValue] [description]	描述接口请求头部需要的参数
@apiSuccess [(group)] [{type}] field [description]	接口成功返回参数
@apiError [(group)] [{type}] field [description]	错误返回参数
@apiSuccessExample [{type}] [title] example	返回成功示例
@apiErrorExample [{type}] [title] example	接口错误返回示例
@apiExample [{type}] title example	接口请求示例
@apiSampleRequest url	模拟接口请求
@apiVersion version	定义接口/注释模块版本

创建src目录，在目录下放入你的接口文件，下方是参考代码：

/**
 * @api {POST} /User/login 用户登录
 * @apiName 用户登录
 * @apiDescription 该接口用于用户登录，成功和失败返回详见下方
 * @apiGroup User
 *
 * @apiVersion 1.0.0
 *
 * @apiHeader (Header参数) {string} openid 用户的openid
 * @apiHeader (Header参数) {string} access-token 用户的access-token
 *
 * @apiParam (传入参数) {string} Username 用户名
 * @apiParam (传入参数) {string} password 密码
 * @apiParam (传入参数) {number} [source] 来源
 *
 * @apiSuccess (成功返回字段) {number} code 返回码
 * @apiSuccess (成功返回字段) {string} message 返回信息
 * @apiSuccess (成功返回字段) {object} data 返回数据
 * @apiSuccess (成功返回字段) {number} data.id 用户ID
 * @apiSuccess (成功返回字段) {string} data.Username 用户名
 * @apiSuccess (成功返回字段) {string} data.email 邮箱
 *
 * @apiError (失败返回字段) {number} code 返回码
 * @apiError (失败返回字段) {string} message 返回信息
 *
 * @apiSampleRequest https://127.0.0.1/xiaochengxu/api/User/login
 *
 * @apiSuccessExample {json} 成功返回:
 * 		{
 *		 	"code": 0,
 *		 	"message": "登录成功",
 *		 	"data":{
 *			 	"id":"1",
 *			 	"Username": "admin",
 *			 	"email":null
 *			 }
 *		}
 *
 * @apiErrorExample {json} 失败返回:
 *     {
 *         "code": "99",
 *         "message": "帐号或密码错误"
 *     }
 */
function login() {

}

/**
 * @api {GET} /User/logout 注销登录
 * @apiName 注销登录
 * @apiDescription 该接口用于注销登录，成功和失败返回详见下方
 * @apiGroup User
 *
 * @apiVersion 1.0.0
 *
 * @apiDeprecated 废弃了原接口 (#User:exit).
 *
 * @apiHeader (Header参数) {string} openid 用户的openid
 * @apiHeader (Header参数) {string} access-token 用户的access-token
 *
 * @apiParam (传入参数) {number} id 用户id
 * @apiParam (传入参数) {number} [source] 来源
 *
 * @apiSuccess (成功返回字段) {number} code 返回码
 * @apiSuccess (成功返回字段) {string} message 返回信息
 *
 * @apiError (失败返回字段) {number} code 返回码
 * @apiError (失败返回字段) {string} message 返回信息
 *
 * @apiExample {curl} 请求案例：
 * https://127.0.0.1/xiaochengxu/api/User/logout?id=18
 *
 * @apiSampleRequest https://127.0.0.1/xiaochengxu/api/User/logout
 *
 * @apiSuccessExample {json} 成功返回:
 * 		{
 *		 	"code": 0,
 *		 	"message": "注销成功"
 *		}
 *
 * @apiErrorExample {json} 失败返回:
 *     {
 *         "code": "-1",
 *         "message": "注销失败"
 *     }
 */
function logout() {

}


/**
 * @api {GET} /User/exit 注销登录
 * @apiName 注销登录
 * @apiDescription 该接口用于注销登录，成功和失败返回详见下方
 * @apiGroup User
 *
 * @apiVersion 0.0.8
 *
 * @apiDeprecated 该接口已废弃 (#User:exit).
 *
 * @apiParam (传入参数) {string} Username 帐号
 * @apiParam (传入参数) {number} [source] 来源
 *
 * @apiSuccess (成功返回字段) {number} code 返回码
 * @apiSuccess (成功返回字段) {string} message 返回信息
 *
 * @apiError (失败返回字段) {number} code 返回码
 * @apiError (失败返回字段) {string} message 返回信息
 *
 * @apiSuccessExample {json} 成功返回:
 * 		{
 *		 	"code": 0,
 *		 	"message": "注销成功"
 *		}
 *
 * @apiErrorExample {json} 失败返回:
 *     {
 *         "code": "-1",
 *         "message": "注销失败"
 *     }
 */
function exit() {

}

dos命令切换到配置文件所在目录，执行生成命令：

apidoc -i src/ -o apidoc/

参数列表：

参数	描述
-h, --help	查看帮助文档
-f --file-filters	指定读取文件的文件名过滤正则表达式(可指定多个)例如: apidoc -f “..js" − f " . ∗ . t s " -f ".\.ts"−f".∗.ts” 意为只读取后缀名为js和ts的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters	指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc -e “.*.js$” 意为不读取后缀名为js的文件默认:’’
-i, --input	指定读取源文件的目录例如：apidoc -i myapp/ 意为读取myapp/目录下面的源文件默认值:./
-o, --output	指定输出文档的目录例如：apidoc -o doc/ 意为输出文档到doc目录下默认值:./doc/
-t, --template	指定输出的模板文件例如:apidoc -t mytemplate/默认:path.join(__dirname, ‘…/template/’)(使用默认模板)
-c, --config	指定包含配置文件(apidoc.json)的目录例如:apidoc -c config/默认:./
-p, --private	输出的文档中是否包含私有api例如:apidoc -p true 默认:false
-v, --verbose	是否输出详细的debug信息例如:apidoc -v true默认:false

如果报错，说明执行失败，根据错误信息进行修改

执行成功后，会自动生成一个apidoc文件夹，里面包含了接口文档

生成的接口文档：

不同的版本可以进行切换查看和对比（红色是删除，绿色为新增）：

更多信息，可参考官网：https://apidocjs.com/