ApiDoc使用详解
参考项目文档：apidoc官方文档
1. 安装apidoc
注意：首先要安装
npm网上搜索
安装命令：npm install apidoc -g
2.安装grunt modulenpm install grunt-apidoc --save-dev
3.配置apidoc.json或者package.json文件
1 | { |
4.apidoc接口文档参数详解
@api {method} /path/to/:uid [title]注：定义接口名，请求方式,路径（必填，除了apiDefine）
1
2
3/**
* @api {post} /user/reg 用户注册
*/@apiDefine name [title]注：定义公共文档块，可使用apiUse在其他文档中插入
1
2
3
4
5
6
7
8
9/**
* @apiDefine MyError
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
/**
* @api {get} /user/:id
* @apiUse MyError
*/@apiDescription text注：接口描述
1
2
3/**
*@apiDescription 用户登录接口
*/@apiName name注：接口名（必填，用户文档左侧菜单二级分类）
1
2
3/**
*@apiName login
*/@apiGroup group注：接口分组（必填，用户文档左侧菜单一级分类）
1
2
3/**
*@apiGroup user
*/@apiVersion 1.1.1注：接口版本号（必须是：major.minor.patch格式：1.0.0）
1
2
3/**
*@apiVersion 1.0.0
*/@apiDeprecated text注：未测试
1
2
3/**
*@apiDeprecated text
*/@apiIgnore [hint]注：忽略的接口[hint]为忽略的原因，可选
1
2
3/**
*@apiIgnore hint
*/@apiPermission name注：api的权限名
1
2
3/**
*@apiPermission admin
*/@apiParam [(group)] [{type}] [field=defaultValue] [description]注：接口参数
{type}包括：{String} 字符串，{Boolean}布尔值, {Number}数字, {Object}对象, {String[]}字符串数组
[field] 可选参数field
field 必选参数 field
=’string’ 参数默认值
{type{size}} 代表字符长度{String{6-12}}
[description] 字段描述1
2
3
4
5
6
7
8
9
10
11/**
* @api {post} /user/
* @apiParam {String} [firstname] Optional Firstname of the User.
* @apiParam {String} lastname Mandatory Lastname.
* @apiParam {String} country="DE" Mandatory with default value "DE".
* @apiParam {Number} [age=18] Optional Age with default 18.
*
* @apiParam (Login) {String} pass Only logged in users can post this.
* In generated documentation a separate
* "Login" Block will be generated.
*/@apiSuccess [(group)] [{type}] field [description]注：接口返回值显示
{type}包括：{String} 字符串，{Boolean}布尔值, {Number}数字, {Object}对象, {String[]}字符串数组
field 返回字段名
[description] 字段描述1
2
3
4
5/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname Lastname of the User.
*/@apiSuccessExample [{type}] [title] example注：接口返回值显示
{type}包括：{json}
title 返回说明：
[example] 返回例子1
2
3
4
5
6
7
8
9/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
5.版本比较
要保留两份，后新的版本的时候。保留原来的版本说明，复制修改为新的版本，另外修改新的版本号
1 | /** |
