接口文档编写规范(前后端分离项目接口api)

接口文档编写规范

API规范

api 主要包括四部分：uri、请求方式、请求参数、返回参数，一般就是对这四部分做统一规范

接口url：是否是rest风格的，统一标识，比如登录的url: /login、比如查询列表以/list 结尾等

请求方式: GET 或者 POST

请求参数:

返回参数：就是返回结果，需要对返回结果进行统一

{
    "success": true,
    "code": 200,
    "msg": "success",
    "data": "token"
}
1
2
3
4
5
6

▷ 接口返回结果 统一的数据结构：

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "data": {},
    "status": 0,
    "message": "给用户的提示信息"
}
1
2
3
4
5
6
7
8

对返回的结果进行规定：都要包含数据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);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

/* 状态码的值-封装到枚举类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;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

uri 和 url 区别：

URL 的常见定义格式为：协议://主机[:端口号]/资源访问路径/…/[?请求参数]

url 是统一资源定位符，而 uri 是统一资源标识；URL是一种具体的URI，可以把url当做一种规范接口，而url是其中的一种具体实现

还有一些约定

默认值、权限约定等等

• 比如分页的字段page默认值是1，size 默认值是10
• 年级字段，使用数字1-6表示，1表示一年级
• 路径 /u/ 代表是已登录状态才能访问的接口

如果本文对你有帮助的话记得给一乐点个赞哦，感谢！