接口文档编写规范
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/ 代表是已登录状态才能访问的接口
如果本文对你有帮助的话记得给一乐点个赞哦，感谢！
