RAP2 API文档编写规范

一、概念

1、RAP2

RAP是一个可视化接口管理工具 通过分析接口结构，动态生成模拟数据，校验真实接口正确性， 围绕接口定义，通过一系列自动化工具提升我们的协作效率。

2、接口文档作用

在前端开发过程中，我们需要实时与后端进行数据交互。然而大多数时候，前端开发都是在没有后端数据提供的情况下进行的，这时我们就需要用到假数据模拟。
rap2就是一款在线模拟数据生成器，可以拦截Ajax请求，其作用在于帮助前端工程师独立于后端进行开发，实现前后端分离。

2、团队

根据业务分类建立相对应的团队，并且添加相关开发；如浙里养、社管社救等

3、仓库

在对应团队下新建仓库

5、模块

根据需求建立对应模块

• 移动端可以按功能划分模块，如找服务可以当作一个模块，相关接口全部写入到这个模块。
• 大屏可以按屏划分模块，如一张大屏一个模块，模块名用大屏名称即可。

二、接口

1、名称

根据需要编写接口的模块标题填写，尽量和UI图名称保持一致，方便对接查找

2、URL地址

/five-help/subsistence-allowance/occupation/count

• 第一个单词为项目名,整个仓库使用同一个
• 第二个单词为模块名，整个模块使用同一个
• 之后的字段根据对应需求设置合适名称
• 词组之间用 - 分隔
• 关键词api不可作为路径名

注意：
1、禁用拼音首字母,统一使用英文单词
2、前端data下api文件夹根据路径建立对应文件

3、入参、出参

注意：
1、禁用拼音首字母,统一使用英文单词
2、多个字段统一小驼峰写法，禁用 横杆（user-name）、下划线(user_name)或全小写(username) 分割
3、特殊情况请使用附录《入参、出参 字段表》
4、出参格式参考实例

3.1 响应内容

默认结构

{
    "data": "",
    "message": "成功",
    "status": 200
}

3.2 生成规则

注意：
1、根据mokjs规则编写，详细规则可查看新建模块后的示例接口 或 访问Mockjs官网
2、生成规则必须填写

3.3 初始值

注意：
1、根据类型 填写对应值
2、默认值必须填写

3.4 简介

注意：
1、根据字段 填写对应简介
2、简介必须填写【data、message、status、code、success除外】

三、实例

1、分页列表

入参：

• pageSize 分页大小
• pageNum 当前页码

{
    pageSize: 15,
    pageNum: 1
}

响应：

• count 总条数
• list 记录集合

{
    data:{
        count: 100,
        list: [
            {
                xx:xx,
                xx:xx
            }
        ]
    },
    msg:{},
    status:200
}

2、对象

{
  "data": {
    "title": "汪芳",
    "projectName": "平于过该例三酸",
    "status": 1,
    "url": [
      {
        "fileName": "status2.png",
        "imgUrl": "/upload/mz/2021/12/20/mz_1639999211685t5C0q5Z9O1R3_t01.png\n",
        "url": "http://dj.vaiwan.com:80/web/upload/mz/2021/12/20/mz_1639999211685t5C0q5Z9O1R3_t01.png"
      }
    ]
  },
  "message": "查询成功！",
  "success": true
}

3、数组

{
  "data": [
      {
        "fileName": "status2.png",
        "imgUrl": "/upload/mz/2021/12/20/mz_1639999211685t5C0q5Z9O1R3_t01.png\n",
        "url": "http://dj.vaiwan.com:80/web/upload/mz/2021/12/20/mz_1639999211685t5C0q5Z9O1R3_t01.png"
      },
      {
        "fileName": "status2.png",
        "imgUrl": "/upload/mz/2021/12/20/mz_1639999211685t5C0q5Z9O1R3_t01.png\n",
        "url": "http://dj.vaiwan.com:80/web/upload/mz/2021/12/20/mz_1639999211685t5C0q5Z9O1R3_t01.png"
      }
    ],
  "message": "查询成功！",
  "success": true
}

4、Echarts图标

4.1、柱状图

• 基础柱状图

{
  "code": "00",
  "data": {
    "datas": [
      {
        "name": "低保",
        "value": [
          4262,
          415,
          1147,
          755,
          2197,
          528,
          2291,
          4267,
          4214,
          1864,
          8939,
          1652
        ]
      }
    ],
    "titles": [
      "贵阳市",
      "阜新市",
      "眉山市",
      "达州市",
      "韶关市",
      "咸宁市",
      "上海市",
      "随州市",
      "海口市",
      "鸡西市",
      "黔东南苗族侗族自治州",
      "白城市"
    ]
  },
  "message": "查询成功！",
  "pkid": "",
  "success": "true"
}

• 简单数据集-柱状图

{
  "data": {
    "datas": [
      {
        "name": "收入型",
        "value": [
          2030,
          4080,
          8879,
          5258,
          9746,
          768,
          732,
          5223,
          2284,
          5582,
          4904,
          232
        ]
      },
      {
        "name": "残疾人单列户",
        "value": [
          6441,
          7646,
          632,
          647,
          8125,
          3174,
          6452,
          2537,
          1260,
          9654,
          1789,
          6757
        ]
      },
      {
        "name": "支持类型",
        "value": [
          4179,
          8679,
          7753,
          7705,
          455,
          6747,
          4266,
          4762,
          3107,
          2839,
          3729,
          3617
        ]
      },
      {
        "name": "重病型单列户",
        "value": [
          8654,
          9531,
          6403,
          2432,
          3158,
          5299,
          1659,
          8385,
          1013,
          6263,
          691,
          9807
        ]
      }
    ],
    "titles": [
      "阿勒泰地区",
      "榆林市",
      "日照市",
      "荆州市",
      "南阳市",
      "运城市",
      "阜新市",
      "盘锦市",
      "香港岛",
      "湘西土家族苗族自治州",
      "泰州市",
      "三明市"
    ]
  },
  "message": "查询成功！",
  "pkid": "",
  "success": "true"
}

附录

一、入参、出参 字段表

字段 | 描述 ---|--- provinceId | 省ID provinceName | 省名 cityId | 行政区划ID、市IDququ cityName | 区划名称、市名 areaId | 区ID areaName | 区名 pageSize | 分页大小 pageNum |当前页码 count | 总计、统计、全部 name | 名字 title | 标题 list | 列表

二、接口常见问题

1. 数据格式问题:

响应内容里必须有：

1. data: [] | {}
2. success: 'true'
3. message: '查询成功'
4. status: 200

2. 请求参数的正确与错误比对:

错误:

正确:

3. 数据结构问题:

嵌套层数过多时，可能导致获取不到数据

例如：

data: {
  list: [
    {
      name: '',
      age: ''
    },
    {
      name: '',
      age: ''
    }
  ]
}

正确格式为:

data: [
  {
    name: '',
    age: ''
  },
  {
    name: '',
    age: ''
  }
]

4. 图表接口返回的数据问题:

关于柱状图、饼图、折线图等图表所需要的数据结构是固定的 详细参照实例下的Echarts图表结构进行返回数据

5. 模块划分问题:

不同的页面接口不可以写再同一个模块内 应当以各各页面的名字来创建模块 将接口整理到对应的模块内

例如:

对应：