apidoc生成文档使用

1、首先全局安装apidoc
命令：

npm install apidoc -g

2、安装完成，查看是否安装上

apidoc -h

3、在项目根目录建apidoc.json文件

{
  "name": "Api文档",
  "title": "Api文档",
  "description": "描述",
  "url": "http: //127.0.0.1:3000",
  "version": "1.0.0"
}

4、生成文档的命令

// 例如：routes是文档的目录
apidoc -i routes/ -o public/apidoc/

5、示例：

/**
 * @api {post} /ncp/login 密码登录
 * @apiDescription 密码登录
 * @apiName loginPassword
 * @apiGroup 登录
 * @apiParam {string} phone 手机号码
 * @apiParam {string} password 密码
 *  @apiHeader (输入token) {string} access-token 请求头
 * @apiSuccess (成功状态) {string} status 成功状态码200
 *  * @apiSuccessExample  {json} 返回数据格式
*{
  *  "msg": "登录成功",
  *  "status": 200
*}
 * @apiError (失败状态){string} status 返回错误消息400
 *  * @apiErrorExample  {json} 返回数据格式
 * {
 *   "msg": "用户名不存在",
 *   "status":400
 * }

 * @apiSampleRequest http://localhost:3000/api/login
 * @apiVersion 1.0.0
 */

基础参数介绍

@api

/** 
 * @api {method} path [title]
 */

参数	描述
method	请求的方法名称：如GET、POST等等
path	请求路径
title	接口名称

@apiGrou定于api归属的组名，生成的文档会把该api注释归类到该值对应的api组上

参数	描述
name	归属名称

@apiName用于定义API文档的一个实例，并用作实例名称

/**
 * @apiName name
 */

参数	描述
name	实例名称

@apiHeader设置请求头

/**
*  @apiHeader (提示) {type} name 请求头
*/

参数	描述
type	数据类型(string,number等)
name	请求头字段(比如：access-token)

@apiParam携带的参数

/**
@apiParam {type} phone decs
*/

参数	描述
type	数据类型(string,number等)
phone	字段
decs	描述(比如：手机号码必传)