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

迈不过友情╰ 2024-04-06 12:19 72阅读 0赞

## 接口文档编写规范 ##

### API规范 ###

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

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

#### 请求方式: GET 或者 POST ####

#### 请求参数: ####

<table> 
 <thead> 
  <tr> 
   <th>参数名称</th> 
   <th>参数类型</th> 
   <th>说明</th> 
   <th>是否必填</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>account</td> 
   <td>string</td> 
   <td>账号</td> 
   <td>是</td> 
  </tr> 
  <tr> 
   <td>password</td> 
   <td>string</td> 
   <td>密码</td> 
   <td>是</td> 
  </tr> 
 </tbody> 
</table>

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

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

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