简介
在代码中插入一定规范的注释，apidoc通过运行相应的命令去解析，帮助我们生成接口文档
apidoc.json配置
-
name：名字 -
version：版本号 -
description：描述信息 -
title：标题 -
url：api路径的前缀 -
header：有两个属性:title(header.md的导航文本，不想显示导航可以设置成空字符串)和filename(md文件地址，会放在api文档顶部) -
footer：有两个属性:title(footer.md的导航文本，不想显示导航可以设置成空字符串)和filename(md文件地址，会放在api文档底部)
基本注释规范
-
@api {method} path [title]：必须的（required） -
@apiVersion version：当前api的版本号 -
@apiName name：当前api的名字（Should always be used） -
@apiGroup name：当前api所属分组（Should always be used） -
@apiDescription text：描述这个api的描述信息 -
@apiExample [{type}] title example：api示例 -
@apiHeader [(group)] [{type}] [field=defaultValue] [description]：放在请求头中，一般是用来进行校验，如authorization -
@apiHeaderExample [{type}] [title] example：请求头参数示例 -
@apiParam [(group)] [{type}] [field=defaultValue] [description]：请求参数，类型，可以包括默认值和参数描述 -
@apiParamExample [{type}] [title] example：请求参数示例 -
@apiPermission name：当前api需要的权限。比如，某些api要求头部必须anthorization等 -
@apiSuccess [(group)] [{type}] field [description]：响应成功的返回参数 -
@apiSuccessExample [{type}] [title] example：响应成功的返回示例 -
@apiError [(group)] [{type}] field [description]：定义错误类型，如{4XX}错误，{5XX}错误 -
@apiErrorExample [{type}] [title] example：错误响应的示例 -
@apiSampleRequest url：用来点击发送示例请求的地址 -
@apiDefine name [title] [description]：定义公共代码块，然后可以通过@apiUse使用 -
@apiUse name：使用@apiDefine定义好的代码块 -
@apiIgnore [hint]：忽略某些api。比如某些方法未完成不想暴露给外面，就是用这个注解
基本使用
-
安装：
npm i apidoc --save-dev -
在根目录下添加配置文件
apidoc.json
{
"name": "apidoc-demo",
"version": "1.0.0",
"description": "使用apidoc生成的接口文档",
"title": "apidoc-demo",
"url" : "http://localhost:3000"
}
- 在
controller/目录下的文件里面添加注释
/**
* @api {get} /suggestions/front_page 首页列表
* @apiVersion 1.0.0
* @apiGroup Pumpkin
* @apiDescription 获取用户列表
*
* @apiParam {Number} offset 偏移量
* @apiParam {Number} size 每页的数量
*
* @apiSuccess {Object[]} data 返回数据
* @apiSuccess {String} data.type 类型
* @apiSuccess {Number} data.id id
* @apiSuccess {String} data.title 标题
* @apiSuccess {Object} data.user 用户
* @apiSuccess {Number} data.user.userid 用户id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "errcode" : 0,
* "message": "",
* "data" : [{
* "name" : "userName",
* "email" : "userEmail"
* }]
* }
*/
-
在根目录下新建
apidoc/目录 -
修改
package.json文件，在scripts里面添加命令
{
// ...
"scripts": {
// ...
"apidoc": "apidoc -i controller/ -o apidoc/"
},
// ...
}
-
执行
npm run apidoc，即可在apidoc/目录下生成index.html文件和对应的资源文件 -
打开
apidoc/目录下的index.html即可看到效果
header & footer
-
在
apidoc/目录中新建header.md文件 -
修改
apidoc.json文件，添加header（footer类似）
{
// ...
"header": {
"title": "",
"filename": "apidoc/header.md"
}
}
抽离公共代码块
@apiDefine抽离公共块
@apiUse使用公共块
- 在
controller/目录下新建apidoc_common.js（文件名随意）
// 抽离公共代码块
/**
* @apiDefine CommonSuccess 成功响应字段公共部分
* @apiSuccess {Number} errcode The success res code.
* @apiSuccess {Strng} message The res message.
*/
/**
* @apiDefine token 需要验证用户权限
* 需要在header中加入Authorization字段进行用户权限验证
*/
/**
* @apiDefine InvalidToken 权限认证失败
* @apiError (Error 5xx) {401} InvalidToken 用户权限校验不通过
* @apiErrorExample {json} Error-response
* Http/1.1 401 Unauthorize
* {
* "error": "UserNotFound"
* }
*/
- 其他文件中使用示例
/**
* @api {get} /suggestions/front_page 首页列表
* @apiVersion 1.0.0
* @apiGroup Pumpkin
* @apiDescription 获取用户列表
*
* @apiParam {Number} offset 偏移量
* @apiParam {Number} size 每页的数量
*
* @apiUse CommonSuccess
* @apiSuccess {Object[]} data 返回数据
* @apiSuccess {String} data.type 类型
* @apiSuccess {Number} data.id id
* @apiSuccess {String} data.title 标题
* @apiSuccess {Object} data.user 用户
* @apiSuccess {Number} data.user.userid 用户id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "errcode" : 0,
* "message": "",
* "data" : [{
* "name" : "userName",
* "email" : "userEmail"
* }]
* }
*
* @apiUse InvalidToken
*
*/
/**
* @api {get} /playlist/list 音乐列表
* @apiVersion 1.0.0
* @apiGroup Pumpkin
* @apiDescription 获取音乐列表
*
* @apiUse CommonSuccess
* @apiSuccess {Array} data 数据
*/
发表评论