前端定义接口需求文档

前言：为什么需要前端去定义接口需求文档呢。

1. 后端的接口文档不一定是靠谱的。他们使用的swagger文档，有的时候是针对某个字段只是表示一个对象，但是对象里有哪些字段就没有了。
2. 后端提供的接口文档，请求参数是否必填不明确；响应参数给的字段太多了。而我们需要的参数却只有几个。
3. 【很重要】前端没有接口文档，常常就会沦为后端的接口测试员。后面工期全压到前端身上了，延期的责任变成前端的了，需要前端天天加班工作。
   前端有接口文档，完全可以脱离后端的进度。没有数据，就自己造 mock数据。

一、接口字段定义

前端的接口文档要求：

1. 前端不去定义接口的具体URL地址 和 字段名。主要是整理出需要哪些入参和响应。
2. 请求参数字段和响应字段，只写前端需要的字段。中文描述名先填好，英文字段名后面填写（如果后端给的文档不明确，直接让后端填）。
3. 请求参数字段 需要 表明 是否必填，是否条件存在，

 

 

演示：

• 入参：
  

  字段说明	字段名	备注
  *姓名	name
  *年龄	age

  
  参考数据：【用来联调时，使用的数据】
  

  {
    name: “zhagnsan”,
    age: 17
  }

• 出参：
  

  字段说明	字段名	备注

 

总结一句话：前端一定要有自己写的接口文档。如果后端有提供内容完备的接口文档，才可以不用自己写。如果后端的接口不完备，前端需要直接写一份。总之这个就是划分工作责任的材料。

 

二、数据结构规范

　　这个只要是统一下，接口的出参结构。https://mp.weixin.qq.com/s/_NqcdH6UPME9kHo5hjAZwA 
　　这个参数结构的问题，对前端前期开发的影响到大。后面结构不对，修改下也方便的。

• 入参结构：
  

  {
    name: "dfd",
    age: "dfad"
  }

• 出参结构

  {
      code: 200,
      data: {  // 数据放在 data属性下
          message: "success",
          entity: {
              id: 1,
              name: "XXX",
              code: "XXX"
          }
      }
  }