apiDoc接口文档与平时接口使用规范

1.安装node.js环境（Windows环境）

注意：不要拿太低版本的node安装apiDoc，会报各种问题，我就之前用了6.1的版本安装不成功，尽量用官网最新稳定版本
https://nodejs.org/zh-cn/
查看环境是否安装成功

node -v
npm -v

这里我安装的是 v12.16.1版本

2.安装apiDoc

npm install apidoc -g

查看apiDoc是否安装成功,出现以下信息表示成功安装

apidoc -v

3.新建一个测试项目

test文件夹作为项目目录

4.在test文件夹内创建apidoc.json和header.md、footer.md文件

apidoc.json内容为

{
  "name": "YSRoom-v1.0",
  "title": "API接口文档v1.0-rht",
  "description":"远山小屋API接口文档v1.0",
  "url" : "http://xxxxxx.com/index.php",
  "sampleUrl":"http://liuyuanshan.top/index.php",
  "version": "1.0.0",
  "header": {
    "title": "文档说明",
    "filename": "header.md"
  },
  "footer": {
    "title": "文档结尾",
    "filename": "footer.md"
  }
}

5.在test文件夹内创建src文件夹

在src文件夹内编写file.js文件，也可以是后缀为 .php或.java文件

/**
* @api {post} /admin/goods/friendbusiness  商品列表
* @apiGroup Admin/goods
* @apiDescription  用于后台商品列表展示                              
* @apiVersion 1.0.0
*
* @apiParam {Number} [px]  页码
* @apiParam {Number} [pz]  每页显示的条数
* @apiParam {String} status  上架、下架   
* @apiParam {Number} [weight]   权重
* @apiParamExample {json} Request Example
*   {
*      'code':200,
*      'msg':'操作成功',
*      'data':{
*          'gid':'26735',//商品id
*          'username':'262060984',//用户名
*          'webname':'dsd',//网站名称
*          'url':'dsd12122sdsd.com',//网站地址
*          'bdweight':'0',//权重
*          'sales':'0',//订单数
*          'price':'34.00',//价格
*          'sell_time':'1502868137',//添加时间
*          'sellstatus':'下架',//上下架状态
*      },
*   }
 */

6.执行命令

参数描述
-i 选择源代码所在位置
-o 选择生成的目标文件所在的位置
这里需要在test目录内执行一下命令

apidoc -i src/ -o apidoc/

显示结果页

显示结果页

Apidoc说明：

@api {method} path [title]
  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单
  method可以有空格，如{POST GET}
@apiGroup name
  分组名称，被解析为导航栏菜单
@apiName name
  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
@apiDescription text
  接口描述，支持html语法
@apiVersion verison
  接口版本，major.minor.patch的形式
@apiIgnore [hint]
  apidoc会忽略使用@apiIgnore标注的接口，hint为描述
@apiSampleRequest url
  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种
@apiDefine name [title] [description]
  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块
  在@apiDefine内部不可以使用@apiUse
@apiUse name
  引入一个@apiDefine的注释块
@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
  用法基本类似，分别描述请求参数、头部，响应错误和成功
  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  用法完全一致，但是type表示的是example的语言类型
  example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)
@apiPermission name
  name必须独一无二，描述@api的访问权限，如admin/anyone

接口注释规范：

* @api {请求方式} /模块/控制器/方法  接口中文名称
* @apiGroup 模块/控制器
* @apiDescription  接口描述                              
* @apiVersion 1.0.0 接口版本
* @apiParam {请求参数类型} [字段名]  中文说明
* @apiHeader (输入token：) {string} AppAuthorization
* @apiError (失败返回：) {string}   code 返回错误码 0
* @apiError (失败返回：){string}    msg 返回错误消息
* @apiSuccess (成功返回：) {string}      code 返回正确代码 1
* @apiSuccess (成功返回：) {string}        msg 返回正确信息
* @apiSuccess (成功返回：) {string}        data 返回正确信息
* @apiParamExample {返回参数格式} Request Example
*   {
*      'code':状态码,
*      'msg':'状态说明',
*      'data':{
*          '键':'值',//返回参数说明      
*      },
*   }

结语

这篇文章主要目的是向大家介绍这个工具, 起到快速入门的目的. 这款工具有许多的细节如自定义状态码, 过期API, 权限管理等, 因官网解释已经足够通俗易懂, 就不再此赘述了.建议移步官方http://apidocjs.com/

【参考文档】
https://zhuanlan.zhihu.com/p/83487114
https://www.jianshu.com/p/34eac66b47e3