接口文档——前后端分离开发模式下的“契约书“
一、概述
接口文档是开发团队之间进行API交互的重要技术文档，它详细描述了API的使用方式、参数格式、返回值等信息，作为前后端分离开发模式下的"契约书"。
二、基本结构
1. 接口基本信息
接口名称：简洁明了地描述接口功能
接口地址：完整的URL路径（如：
/api/v1/user/login）请求方法：GET/POST/PUT/DELETE等
请求格式：包含必要的认证信息（如Token）和内容类型
版本号：记录当前API版本（如v1.2.3）
2. 请求参数
路径参数：URL中包含的参数（如
/users/{id}）查询参数：GET请求中的参数（如
?page=1&size=10）请求体：POST/PUT请求中的JSON/XML数据
参数说明：
参数名
类型（String/Number/Boolean等）
是否必填
默认值
取值范围/格式
示例值
描述说明
3. 响应内容
响应状态码：200/400/401/500等HTTP状态码
响应头：包含的特殊头信息
响应体：JSON/XML格式的返回数据
字段说明：
字段名
类型
示例值
描述说明
可能的值枚举
4. 错误码说明
定义各种可能的错误码及其含义
错误码分类（如1xxx表示系统错误，2xxx表示业务错误）
每种错误码对应的解决方案建议
三、示例模板
1. 查找
作用：用于查找内容信息
请求路径：SearchContent
请求方式：get
传输数据格式：json
请求入参：
Channelid (栏目id) 类型：字符串 非必传 注释：参数为0表示无效
Title(内容标题) 类型：字符串 非必传
Author(作者) 类型：字符串 非必传
Page(页码) 类型：字符串 非必传
PageSize(一页大小) 类型：字符串 非必传
Id(内容id) 类型：字符串 非必传
数据样本：
{
Channelid：1,
Title:”文章标题”,
Author:”文章作者”,
Page:1,
PageSize:5,
Id:5
}
响应的出参：
Code(状态) 类型:整数 必有
Msg(信息) 类型:整数 必有
Data(查找到的内容) 类型:数组 必有
出参样本：
{
Code:0,
Msg:”ok”,
Data:[{
Id:1,
Title:”标题”,
Author:”作者”,
Createtime:”2028-08-17”,
Imgurl:”123456.jpg”,
Content:”文章内容”,
Channelid:1,
ChanneiName:”通知公告”
},{},{}]
}
查找失败：
{
Code:0,
Msg:”ok”,
Data:[]
}
2. 删除
作用：用于删除内容信息
请求路径：DeleteContent
请求方式：post
传输数据格式：json
请求入参：Id(内容id) 类型：字符串 必传
数据样本：
单个删除：
{
Id:”5”
}
批量删除
{
Id:”5,8,9”
}
响应的出参：
Code(状态) 类型:整数 必有
Msg(信息) 类型:整数 必有
出参样本：
删除失败：
{
Code:0,
Msg:”删除失败”
}
删除成功：
{
Code:1,
Msg:”删除成功”
}
四、错误码
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 4001 | 用户名或密码错误 | 检查输入或重置密码 |
| 4002 | 验证码错误 | 重新获取验证码 |
| 5001 | 系统繁忙 | 稍后重试或联系管理员 |