首页 > 其他分享 >接口文档编写规范(前后端分离项目接口api)

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

时间:2022-09-23 13:01:22浏览次数:52  
标签:code String 接口 api 文档 Result msg public

接口文档编写规范

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/ 代表是已登录状态才能访问的接口




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

标签:code,String,接口,api,文档,Result,msg,public
From: https://www.cnblogs.com/shan333/p/16722342.html

相关文章