欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

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

程序员文章站 2022-04-28 16:27:34
...

1.安装node.js环境(Windows环境)

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

node -v
npm -v

这里我安装的是 v12.16.1版本
apiDoc接口文档与平时接口使用规范

2.安装apiDoc

npm install apidoc -g

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

apidoc -v

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

3.新建一个测试项目

test文件夹作为项目目录
apiDoc接口文档与平时接口使用规范

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

apiDoc接口文档与平时接口使用规范
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 选择生成的目标文件所在的位置
apiDoc接口文档与平时接口使用规范这里需要在test目录内执行一下命令

apidoc -i src/ -o apidoc/

显示结果页

apiDoc接口文档与平时接口使用规范显示结果页
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

相关标签: APP接口开发