接口文档规范 - gozgroup/goz-portal GitHub Wiki

接口文档规范

• 接口名称
• 场景说明
• 接口说明
• 请求参数
• 响应参数
• 错误码

参数

• 字段名
• 变量名
• 是否必填
• 类型
• 示例值
• 描述

错误码

• 名称
• 描述
• 原因
• 解决方案

示例

1.查询某个用户

（1）场景说明

用户A可以查询有效用户B，可获取用户B的基本信息（用户名、昵称、性别、头像）

（2）接口说明

说明		备注
地址	api.gozmen.com/user
方式	POST

（3）请求参数

RequestHeader

名称	必填	说明
Content-Type	是	application/x-www-form-urlencoded; application/json

表单参数（Content-Type: application/x-www-form-urlencoded）

名称	类型	必填	说明
id	string	是	用户id

Json请求数据

{
    "id":"userId"
}

（4）相应参数

ResponseHeader

名称	必填	说明
Content-Type	是	application/x-www-form-urlencoded; application/json

Json返回数据

{
    "code":0,
    "error":"ok",
    "data":{
        "nick":"nick",
        "username":"username"
    }
}

{
    "code":400,
    "error":"not found"
}

（5）错误码

错误类型	说明
400	用户不存在