跳转至

接口文档规范

接口规范#

  1. 功能描述：要详细描述接口的作用，以及不同的参数对返回的结果。
  2. 接口类型：（GET/POST）。
  3. 参数描述：
    1. 参数是否为必填。
    2. 每个参数的描述都要十分详细，不同的接口有相同的参数不要出现 同接口** 的描述。 同接口** 的描述，会让看接口文档的人十分费力，需要跳转到别的地方才能知道这个参数的意义，会影响开发人员的效率。
    3. 参数的类型要描述清楚，比如接收一个对象和一个字符串。
      1
2
3
4
5
6
7
      {
    user:{
        "name":"张",
        "age":"12"
    },
    siteId:'aaaaaaaaaaaaaaa'
}
      1. 返回值：返回值描述需要尽量清晰，需要和功能描述相对应，正常情况和出错的情况下会返回什么数据。

例子#

  1. 用户信息接口。
    1.1. 根据用户名和用户年龄查找用户。 

    1
    GET    ***/searchUserByNameAndAge

    接口描述 ： 根据用户名和年龄查找用户。
    功能描述 ： 根据用户名和年龄查找用户，如果能查询到符合条件的用户则返回查询结果，如果没有符合条件的用户，则返回空数组 []，如果查询出错则返回错误信息,同时返回的数据为空 null。
    参数描述 ：

    name(必填): 用户名，支持全局模糊查询(like)，例如：存在张三和老张这两个用户名，查询张,则张三和老张都会匹配 。
    age (必填): 年龄支持相等(==)查询, age必须为整数，且age的取值范围为[0,150], 如果age的格式不正确或者不在范围之内，则查询会出错。

    参数示例:

    1
2
3
4
    {
    "name":"张",
    "age":"12"
}

    返回数据 : 

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    > sysMsg : 系统信息。
> > > 成功则返回成功提示信息
> > > 出错则返回错误提示信息。  
> success : 是否查询成功。
> > > 成功返回 true
> > > 出错返回 false
> data : 返回查询结果  
> > > 查询成功，返回查询结果数
> > > 没查询到数据返回空数组 []  
> > > 查询出错的时候返回值为空

    • 正确情况：返回预期的查询结果。 

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
      {
    "sysMsg": "查询成功",
    "success": "true",
    "data": [
        {
            "name": "张三",
            "age": "22"
        },
        {
            "name": "老张",
            "age": "22"
        }
    ]
}

    • 出现错误：

      1
2
3
4
5
      {
    "sysMsg": "查询失败的原因",
    "success": "false",
    "data":"null"  
}