restful api 文档规范

API文档规范要求
一、写明该接口的功能是什么
二、请求的URL是什么
三、请求方式是什么（POST、GET、 DELETE、PUT、 PATCH等）
四、参数是什么，此处还需说明你的参数名、参数类型、是否必填、参数的简单解释
五、请求成功时的响应内容（实际开发中，要与前端同事沟通使用什么样的数据结构），并且对其中的字段做出说明（包括含义、数据类型，数据结构<字符串，数组，字典等>）
六、请求失败时的响应内容，并且对其中的字段做出说明（包括含义、数据类型，数据结构<字符串，数组，字典等>）包括单独的对错误码的说明
七、请求样例（返回结果部分要包括成功的情况和失败的情况）
八、最好写上文档的编写人和编写时间（可不写）
Demo：
功能：获取某人的下属
URL：”people/api/v1/ subordinate”
请求参数说明：
参数名 类型 是否必填 备注
uid int 是 用户的id

请求成功参数说明
参数名 类型 说明
code Int 响应状态码1代表成功
msg string 响应信息
data 数组 数组内是字典类型，详情见下表

data内的响应参数说明

参数名 类型 说明
uid int 下属的用户ID
name string 下属的用户名
position string 下属的岗位
请求失败参数说明

参数名 类型 说明
code Int 响应状态码非1值
msg string 错误提示信息

code值说明

Code 说明
1 成功
2 该人已经离职
3 请求参数不完整
4 参数类型错误

样例：
请求参数
uid 1

请求成功样例

{
‘code’: 1,
‘msg’: ‘ok’,
‘data’:[
{
‘uid’:2,
‘name’: ‘Tom’,
‘position’: ‘教师’
},
{
‘uid’:3,
‘name’: ‘Lucy’,
‘position’: ‘助教’
}
]
}
请求失败样例
{
‘data’: 2,
‘msg’: ’该人已离职’
}