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/