接口文档编写规范(前后端分离项目接口api)
接口文档编写规范
API规范
api 主要包括四部分:uri、请求方式、请求参数、返回参数,一般就是对这四部分做统一规范
接口url:是否是rest风格的,统一标识,比如登录的url: /login、比如查询列表以/list 结尾等
请求方式: GET 或者 POST
请求参数:
参数名称 | 参数类型 | 说明 | 是否必填 |
---|---|---|---|
account | string | 账号 | 是 |
password | string | 密码 | 是 |
返回参数:就是返回结果,需要对返回结果进行统一
{
"success": true,
"code": 200,
"msg": "success",
"data": "token"
}
▷ 接口返回结果 统一的数据结构:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"data": {},
"status": 0,
"message": "给用户的提示信息"
}
对返回的结果进行规定:都要包含数据data、状态码status、提示信息message 这三个字段
并且对状态码的值进行规定:比如成功请求状态码是200,发生错误时的各种状态码,比如约定:10001是"参数有误"、10002,"用户名或密码不存在"等等
/* 接口返回结果-封装到Result类中 */
public class Result {
private boolean success;
private int code;
private String msg;
private Object data;
//成功、失败 返回的方法
public static Result success(Object data){
return new Result(true,200,"success",data);
}
public static Result fail(int code, String msg){
return new Result(false,code,msg, null);
}
}
/* 状态码的值-封装到枚举类ErrorCode中 */
public enum ErrorCode {
PARAMS_ERROR(10001,"参数有误"),
ACCOUNT_PWD_NOT_EXIST(10002,"用户名或密码不存在"),
TOKEN_ERROR(10003,"token不合法"),
ACCOUNT_EXIST(10004,"账号已存在"),
NO_PERMISSION(70001,"无访问权限"),
SESSION_TIME_OUT(90001,"会话超时"),
NO_LOGIN(90002,"未登录");
private int code;
private String msg;
ErrorCode(int code, String msg){
this.code = code;
this.msg = msg;
}
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getMsg() {
return msg;
}
public void setMsg(String msg) {
this.msg = msg;
}
}
uri 和 url 区别:
URL 的常见定义格式为:协议://主机[:端口号]/资源访问路径/.../[?请求参数]
url 是统一资源定位符,而 uri 是统一资源标识;URL是一种具体的URI,可以把url当做一种规范接口,而url是其中的一种具体实现
还有一些约定
默认值、权限约定等等
- 比如分页的字段page默认值是1,size 默认值是10
- 年级字段,使用数字1-6表示,1表示一年级
- 路径 /u/ 代表是已登录状态才能访问的接口
如果本文对你有帮助的话记得给一乐点个赞哦,感谢!
本文来自博客园,作者:一乐乐,转载请注明原文链接:https://www.cnblogs.com/shan333/p/16722342.html