当前调试都是在apidoc@0.28.1版本下执行的,有不对的地方欢迎指出
安装apidoc
npm i apidoc --save-dev
配置apidoc
可以有以下三种形式存放配置
package.json
{
"apidoc": {
"name": "projectName",
"url": "http://apiservice.com",
"version": "1.0.0"
// 此处省略更多apidoc配置
}
}
apidoc.json
{
"name": "projectName",
"url": "http://apiservice.com",
"version": "1.0.0"
// 此处省略更多apidoc配置
}
apidoc.config.js
module.exports = {
name: "projectName", // 形成的文档名称,如果没有配置,则从package.json中取对应字段
version: "1.0.0", // 当前版本-默认显示的api版本,如果没有配置,则从package.json中取对应字段
description: "project api doc description", // api文档描述,如果没有配置,则从package.json中取对应字段
title: "api文档", // 形成的浏览器页面标题
url: "http://apiservice.com", // api的前缀路径
useHostUrlAsSampleUrl: false, // 使用hosturl当作测试api请求的url前缀 - 经测试感觉无效
sampleUrl: 'http://apiTest.com', // 页面测试api请求的url前缀,会覆盖useHostUrlAsSampleUrl - 这个配置项不设置的话,内部的@apiSampleRequest设置也不起作用
// 头部和尾部文档配置
header: {
title: "headerMenu", // 标题-用于形成左侧菜单名称
filename: "header.md", // 文档内容
},
footer: {
title: "footerMenu", // 标题-用于形成左侧菜单名称
filename: "footer.md", // 文档内容
},
// api-name排序或者group-name排序, 先进行group排序-再进行name排序, 没有的则自动在后面显示
order: [
"login",
"save",
"User",
"Menu"
],
template: {
forceLanguage: 'zh_cn', // 生成apidoc的默认语言,默认zh_cn(中文简体)
withCompare: true, // 是否需要进行版本对比,默认true
withGenerator: true, // 是否需要显示编译信息(主要是编译日期和apidoc版本),默认true
jQueryAjaxSetup: { // 默认的jquery的ajax的配置
headers: {
token: '123'
}
},
aloneDisplay: true, // 是否需要单独显示某个api,默认fale
}
}
生成apidoc
apidoc -i app/routes/ -o app/public/apidoc/
其中app/routes/
是需要解析的目录,app/public/apidoc/
是生成的apidoc文档输出目录
apidoc编写的param
@apiIgnore [msg]
生成文档时忽略该api
/**
* @apiIgnore not finish
* @api {get} /user/login 用户登录
* 生成文档中不会包含此请求的信息
*/
@apiPermission name
说明api权限
/**
* @api {get} /user/login 用户登录
* @apiPermission admin
* 表明admin权限的才可以测试此请求
*/
@api {type} path [title]
定义api路径,以及形成左侧菜单的名称
/**
* @api {get} /user/login 用户登录
* 此请求方式为 get
* 请求路径为 /user/login
* 生成文档中的左侧菜单为 用户登录
*/
@apiDescription text
定义api描述信息
// 描述信息可以多行,生成文档如果想要换行显示,则注释需要间隔一行才行
/**
* @api {get} /user/login 用户登录
* @apiDescription 此api用于用户登录
* 所有用户都可以登录
*
* 但是需要先用手机号注册才行
*/
@apiGroup name
定义api分组名称
/**
* @api {get} /user/login 用户登录
* @apiGroup User
*/
@apiName name
定义api名称
// 此处api名称为login,用于文档生成的定位api的表示
/**
* @api {get} /user/login 用户登录
* @apiName login
*/
@apiParam [(group)] [{type}] [field=defaultValue] [description]
定义参数-可以分组
/**
* @apiParam {String="1-管理员","0-普通用户} type=1 用户类型
* @apiParam {String} [userName] 用户名
*
* @apiParam (address) {String} [city] 城市
* @apiParam (address) {String} [street] 街道
*/
@apiParamExample [{type}] [title] example
定义param的示例
/**
* @apiParamExample {json} Request-Example:
* {
* "name": "首页", // 菜单名称
* "path": "/home", // 菜单路径
* "icon": "home", // 菜单图标-可为空
* "level": 1, // 菜单层级
* "parentCode": "0" // 父级菜单编码
* }
*/
-
@apiBody [{type}] [field=defaultValue] [description]
定义body参数用法同@apiParam
-
@apiError [(group)] [{type}] field [description]
定义error信息用法同@apiParam
-
@apiErrorExample [{type}] [title] example
定义Error的示例用法同@apiParamExample
-
@apiHeader [{type}] [field=defaultValue] [description]
定义header用法同@apiParam
-
@apiHeaderExample [{type}] [title] example
定义Header的示例用法同@apiParamExample
-
@apiSuccess [(group)] [{type}] field [description]
定义返回的数据用法同@apiParam
-
@apiSuccessExample [{type}] [title] example
定义返回的数据的示例用法同@apiParamExample
-
@apiDefine name
定义块 name-块名称 -
@apiUse name
使用定义的块 name-块名称 -
@apiVersion version
定义api版本 version-版本号 -
@apiSampleRequest url
调整示例请求的url
// 经测试,此设置需要在apidoc.config.js中配置sampleUrl才生效
// eg: sampleUrl = http://api.com;
/**
* @api {get} /user/login 用户登录
* @apiSampleRequest off
* 此时会关闭-发送示例请求
*/
/**
* @api {get} /user/login 用户登录
* @apiSampleRequest http://apii.com
* 发送示例请求的url为 http://apii.com
*/
/**
* @api {get} /user/login 用户登录
* @apiSampleRequest http://apii.com/api/login
* 发送示例请求的url为 http://apii.com/api/login
*/
/**
* @api {get} /user/login 用户登录
* @apiSampleRequest /api/login
* 发送示例请求的url为 http://api.com/api/login
*/
-
@apiExample [{type}] title example
api使用示例 -
@apiDeprecated text
弃用
/**
* @apiDeprecated use now (#Group:Name).
*/
@apiPrivate
是否私有的-经测试无效
// 配合行内命令 --private false|true 使用
几个例子
GET /user/list
POST /user/login
GET /menu/tree