Yapidoc NPM | npm.io

Api接口信息自动提交工具

Sample

安装

npm i yapidoc

获取项目ID 和更新token

打开项目配置页: http://yapi.host/project/1/setting

在package.json 配置 apiConfig,scripts

{
  "scripts":{
    "apidoc": "apidoc test/**/*.js controller/**/*.js"
  },
  "apiConfig": {
    "project_id": 1,
    "token": "token"
  }
}

scripts.apidoc 配置格式为：apidoc path1 path2

使用

  $ npm run apidoc

Api接口注释规则

示例：

/**
* 获取新闻列表
* 
* @name 获取新闻列表
* @category 公共分类
* @httpverbs GET
* @path /userlist
* @author laoyi
* 
* @param {Object} req - request
* @param {Number} req.query.type - 新闻类别
* @param {Number} [req.query.page=1] - 页码
* @param {Number} [req.query.size=20] - 每页数量
* 
* @param {Object} res -response
* @param {Function} next - next Handle Function
* 
* @returns {json}
* {
*   "code": 0,
*   "message":"获取成功",
*   "data":{
*     "total": 100,
*     "list":[{
*       "id": 1,
*       "title": "新闻标题",
*       "date": "日期"
*       }]
*   }
* }
*/
function getNewsList(req, res, next) {
  ...
}

@description 内容，可以多行，与其他内容保留一行间隔
@name 接口名称
@category 接口分类，默认为 公共分类；非JSDoc标准标签
@httpvers HTTP Method 支持 GET,POST,PUT,DELETE,OPTIONS,HEAD 非JSDoc标准标签，因@method等同于@name，所以采用此标签
@path HTTP path; 非JSDoc标准标签
@author 作者
@param 参数
- 请求参数必须按 @param {类型} 参数名 - 描述 格式注释
- 类型支持 Number, String, Boolean, Object, Array, Function
- HTTP 参数名称结构 req.[position].[key]
  - req.params.key 表明参数在url的path中
  - req.query.key 表明参数在url的query字符串中
  - req.body.key 表明参数在body中
  - req.cookies.key 表明参数在cookies中
  - req.headers.key 表明参数在headers中
  - req.query.ctype=native 表明query参数ctype有默认值native
  - req.quer.keyword 表明query参数keyword可选
  - req.query.page=1 表明query参数page可选且有默认值1
- 参数描述包含多荐信息用竖线 '|' 隔开；描述过长支持换行
- 参数描述中建议包含示例，表达式 exp:示例值，例如：exp:sw
- 参数如果为枚举值用 key:含义,key2:含义2 格式说明
- 详细说明参考：http://www.css88.com/doc/jsdoc/tags-param.html
@returns 接口返回内容
- 注释格式 @returns {type} 描述, 描述部分另起一行
- {type} 可以为 Json，Raw；Json表示 Content-Type=application/json; Raw暂不支持
- 如果是文件下载或者其他返回内容需在@description说明；非JSDoc标准标签
- 基于mockjs 和 json5，使用注释方式写参数说明