0
点赞
收藏
分享

微信扫一扫

API 文档编写规范(参数篇)

笙烛 2021-09-21 阅读 69

位置、格式

请求参数
HTTP方法 位置 格式 ContentType
GET URL 字符串
POST 请求体 JSON application/json
PUT 请求体 JSON application/json
DELETE 请求体 JSON application/json
返回参数
HTTP方法 位置 格式
GET 响应体 JSON
POST 响应体 JSON
PUT 响应体 JSON
DELETE 响应体 JSON

信息存储

key 仅起引导、定位信息的作用,不保存有效信息

// bad
"list": [
    {"66": "Tony"}
]

// good
"list": [
    {"id": "66", "name": "Tony"}
]

格式

请求参数、返回参数的数据结构,都应该遵守如下规则:

  • 某个资源字段 <2 时,要求结构:扁平化
  • 某个资源的字段 >=2 时,要求结构:非扁平化,面向对象的树形结构
  • 字段职责明确、语义化
// 请求

// bad
{
    "user": {
        "name": "Tony"
    }
}


// good
{
    "name_user": "Tony"
}
// 返回

// bad
"list": [
    {
        "type_search": 1,
        "id_user": 66,
        "name_user": "Tony",
        "sex_user": 1
    }
]

// good
"list": [
    {
        "type_search": 1,
        "user": {
            "id": 66,
            "name": "Tony",
            "sex": 1
        }
    }
]
返回参数格式
顶级属性 作用
data 目的数据
err 一级数据状态码
msg 详细状态信息,包含二级数据状态码、具体描述等
  • 成功响应
{
    data: {
        // ...
    },
    err: 0,
    msg: null
}
  • 失败响应
{
    data: null,
    err: 1,
    msg: {
        err: 1001,
        // ...
    }
}
  • 空响应(成功,但数据为空)
{
    data: null,
    err: 2,
    msg: null
}

特殊场景

场景 方式
文件上传 formData
文件下载 URL

其他

空白字段

即使可选字段的值为空,也需要传递该字段,参数值为 null,而不是直接省略

无效字段

请求参数中,不能带有无效字段

时间戳

统一使用 ISO 8601 时间戳(附带时区信息)
格式:YYYY-MM-DDTHH:MM:SSZ

参数限制
  • 分页范围
  • 账号、密码格式
  • ...
允许同时控制多个资源

需要申请操作的资源,以数组形式,存放到请求参数中

User-Agent

设置 User-Agent 值为 项目名称,防止无效用户访问

UUID
  • 每次请求之前,随机一个UUID,存放到请求头,便于错误追踪
  • 在资源唯一标识符上,使用UUID(varchar)代替 自增主键ID(int)
举报

相关推荐

0 条评论