接口文档编写规范(前后端分离项目接口api)
接口文档编写规范
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/ 代表是已登录状态才能访问的接口
如果本文对你有帮助的话记得给一乐点个赞哦，感谢！
本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！