Interface document writing specifications (front-end and back-end separation project interface api)

Interface document writing specifications

API specification

API mainly includes four parts: uri, request method, request parameters, and return parameters. Generally, these four parts are unified and standardized.

Interface URL: Whether it is REST style, unified identification, such as login url: /login, such as query list ending with /list, etc.

Request method: GET or POST

Request parameters:

parameter name	Parameter Type	illustrate	Is it required?
account	string	account	yes
password	string	password	yes

Return parameter: It is the return result, and the return results need to be unified

{
    
    
    "success": true,
    "code": 200,
    "msg": "success",
    "data": "token"
}

▷ The interface returns a unified data structure:

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

{
    
    
    "data": {
    
    },
    "status": 0,
    "message": "给用户的提示信息"
}

Specify the returned results : they must contain three fields: data, status code, and message.

And the value of the status code is stipulated: for example, the status code of a successful request is 200, and various status codes when an error occurs, such as the agreement: 10001 means "the parameter is incorrect", 10002, "the username or password does not exist", etc.

/* 接口返回结果-封装到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;
    }
}

The difference between uri and url:

The common definition format of URL is: protocol://host[:port number]/resource access path/…/[?request parameters]

url is a uniform resource locator, and uri is a uniform resource identifier; URL is a specific URI, and url can be regarded as a standardized interface, of which url is a specific implementation.

There are some agreements

Default values, permission conventions, etc.

• For example, the default value of the paging field page is 1, and the default value of size is 10.
• Grade field, represented by numbers 1-6, 1 represents first grade
• The path /u/ represents the interface that can only be accessed after logging in.

If this article is helpful to you, please remember to give Yile a like, thank you!