api 文档生成
api-to-doc 根据源代码中的 API 描述创建文档
安装
# npm 安装
npm install api-to-doc -D
# yarn 安装
yarn add api-to-doc -D
使用
在指定目录下的 js 文件中任意位置添加注释
// 示例：
/**
* @api {post} /register 用户注册
* @apiKey handlerRegister
* @apiGroup base 基本信息
* @apiGroupParent
* @apiDescription 用户注册
* @apiHeaderParam {String} [toekn] token
* @apiParam {String} account 账号
* @apiParam {String} password 密码
* @apiParam {String} name 用户名
* @apiParam {String} [email] 邮箱
* @apiParam {String} [phone] 手机号
* @apiParam {String} [avatar] 头像
* @apiReturnParam {Object} data
* @apiCode 400 请求错误
* @apiCode 1005 登录过期
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "token": "",
* }
在 package.jons 中添加下方 scripts，然后执行命令生成文档
apitodoc -i routers/ -o apidoc/
// routers/ 为需要生成文档的目标地址
// apidoc/ 为文档输出地址
注释内容说明
@api
/**
* @api {type} url title
*/
| 参数 | 说明 |
|---|
| {type} | 请求方式 |
| url | 请求地址 |
| title | 请求标题 |
@apiTitle
/**
* @apiKey title
*/
| 参数 | 说明 |
|---|
| title | 比@api title 优先级高 |
@apiKey
- 用于接口排序的 key
- 接收 1 个参数，以空格分隔开
/**
* @apiKey key
*/
@apiDescription
/**
* @apiDescription description
*/
@apiGroup
/**
* @apiGroup group groupName
*/
| 参数 | 说明 |
|---|
| group | 根据 group 进行接口分组 |
| groupName | 分组名称 |
@apiGroupParent
- 上级分组对应 @apiGroup group
- 接收 1 个参数，以空格分隔开
/**
* @apiGroupParent groupParent
*/
| 参数 | 说明 |
|---|
| groupParent | 根据 groupParent 判断是哪个分组的子集 |
@apiHeaderParam
/**
* @apiHeaderParam type [field] desc values default
*/
| 参数 | 说明 |
|---|
| type | 参数类型 |
| field | 字段，加[]表示必填 |
| desc | 说明 |
| values | 可选值 |
| default | 默认值 |
@apiParam
/**
* @apiParam type [field] desc values default
*/
| 参数 | 说明 |
|---|
| type | 参数类型 |
| field | 字段，加[]表示必填 |
| desc | 说明 |
| values | 可选值 |
| default | 默认值 |
@apiReturnParam
/**
* @apiReturnParam type field desc sort
*/
| 参数 | 说明 |
|---|
| type | 参数类型 |
| field | 字段 |
| desc | 说明 |
| sort | 返回字段层级，1: '+'，2: '++'... |
@apiSuccessExample
- 接口请求成功示例
- 以 Success-Response:分隔开
/**
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "token": "",
* }
*/
@apiFailExample
- 接口请求失败示例
- 以 Fail-Response:分隔开
/**
* @apiFailExample Success-Response:
* HTTP/1.1 200 OK
* {
* "status": false,
* "code": 400
* }
*/
@apiCode
/**
* @apiCode code desc
*/
@apiRemark
/**
* @apiRemark remark
*/