接口文档的作用与意义
- 在web项目的前后端分离,开发项目的过程中。作为前后端项目数据交互的渠道–接口,需要由前后端工程师共同定义接口,编写接口文档。大家根据这个接口文档进行开发,直到项目结束前都要一直维护这个文档。
- 接口文档有利于前后端工程师共同进行文件的开发交流
- 在项目维护中或项目人员更迭,方便后期人员查看,维护。
接口的规范
- 接分为四部分:方法,uri,请求参数,返回参数
- 方法:新增(post),修改(put),删除(delete),获取(get),在开发的过程中,需要指明哪种请求方法。一般我们就采用GET/POST方法。
- uri: 一般放置请求的uri地址即可,不允许出现大写字母
- 请求参数和返回参数,都分为5列:字段,说明,类型,备注,是否必填。字段用于标明返回参数名称,说明用于标明参数含义,
类型一般标明参数的类型,备注是一些解释,或者写一些例子,便于前端理解。是否必填用于标明参数是否必填。 - 返回参数由若干种情况
- 只返回接口调用成功还是失败(如新增,删除,修改等),则只有一个结构体:code和message两个参数。
- 如果需要返回某些参数,则有两个结构体:code/message/data,以及data里写返回的参数,data是object类型。
- 如果要有返回列表 , 那么有三个结构体: code/message/data,data里面放置:page/size/total/totalPage/list 5个参数,其中data是object类型,list是Array类型,list里面放object,object里面是具体的参数。
接口文档示例
- 接口详情:
地址 | /student/list |
方式 | GET |
- 请求参数:
字段 | 说明 | 类型 | 备注 | 是否必填 |
page | 页码 | Number | 默认1 | 否 |
size | 页面大小 | Number | 默认10 | 否 |
- 请求参数示例:
{
"page": 1,
"size": 10
}
- 返回参数:
字段 | 说明 | 类型 | 备注 | 是否必填 |
code | 接口状态码 | Number | 成功: 1 失败: 0 | 是 |
message | 接口信息 | String | 成功: sucess 失败: 提示信息 | 是 |
data | Object | 是 |
- data:
字段 | 说明 | 类型 | 备注 | 是否必填 |
page | 页码 | Number | 是 | |
size | 页码大小 | Number | 是 | |
totalPage | 总页数 | Number | 是 | |
list | 学生列表 | Array | 是 |
- list:
字段 | 说明 | 类型 | 备注 | 是否必填 |
id | 学生id | Number | 是 | |
name | 姓名 | Stirng | 是 | |
gender | 性别 | Number | 0: 女生 1: 男生 | 是 |
- 返回参数示例:
{
"code": 1,
"message": "成功",
"data": {
"page": 1,
"size": 10,
"totalPage": 10,
"list": [
{
"id": 1,
"name": "张三",
"gender": 1
},{
"id": 2,
"name": "李华",
"gender": 0
}
]
}
}
后端接口开发规范
- 一般我们可以创建两个类,一个类作为返回基类BaseResp,用于作为返回数据格式的基类。一个类作为错误码枚举类ResultStatus,用于
表示错误状态码及其信息。
一个简单的返回基类如下所示:
package com.quick.utils;
import java.util.Date;
/**
* @param <T>
*/
public class BaseResp<T> {
/**
* 返回码
*/
private int code;
/**
* 返回信息描述
*/
private String message;
/**
* 返回数据
*/
private T data;
private long currentTime;
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
public Object getData() {
return data;
}
public void setData(T data) {
this.data = data;
}
public long getCurrentTime() {
return currentTime;
}
public void setCurrentTime(long currentTime) {
this.currentTime = currentTime;
}
public BaseResp(){}
/**
*
* @param code 错误码
* @param message 信息
* @param data 数据
*/
public BaseResp(int code, String message, T data) {
this.code = code;
this.message = message;
this.data = data;
this.currentTime = new Date().getTime();
}
/**
* 不带数据的返回结果
* @param resultStatus
*/
public BaseResp(ResultStatus resultStatus) {
this.code = resultStatus.getErrorCode();
this.message = resultStatus.getErrorMsg();
this.data = data;
this.currentTime = new Date().getTime();
}
/**
* 带数据的返回结果
* @param resultStatus
* @param data
*/
public BaseResp(ResultStatus resultStatus, T data) {
this.code = resultStatus.getErrorCode();
this.message = resultStatus.getErrorMsg();
this.data = data;
this.currentTime = new Date().getTime();
}
}
一个简单的错误码枚举类如下所示:
package com.quick.utils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
错误码
* @author vector
*
*/
public enum ResultStatus {
// -1为通用失败(根据ApiResult.java中的构造方法注释而来)
FAIL(-1, "common fail"),
// 0为成功
SUCCESS(0, "success"),
error_pic_file(3,"非法图片文件"),
error_pic_upload(4,"图片上传失败"),
error_record_not_found(5, "没有找到对应的数据"),
error_max_page_size(6, "请求记录数超出每次请求最大允许值"),
error_create_failed(7,"新增失败"),
error_update_failed(8,"修改失败"),
error_delete_failed(9,"删除失败"),
error_search_failed(10,"查询失败"),
error_count_failed(11,"查询数据总数失败"),
error_string_to_obj(12,"字符串转java对象失败"),
error_invalid_argument(13,"参数不合法"),
error_update_not_allowed(14,"更新失败:%s"),
error_duplicated_data(15,"数据已存在"),
error_unknown_database_operation(16,"未知数据库操作失败,请联系管理员解决"),
error_column_unique(17,"字段s%违反唯一约束性条件"),
error_file_download(18,"文件下载失败"),
error_file_upload(19,"文件上传失败"),
//100-511为http 状态码
// --- 4xx Client Error ---
http_status_bad_request(400, "Bad Request"),
http_status_unauthorized(401, "Unauthorized"),
http_status_payment_required(402, "Payment Required"),
http_status_forbidden(403, "Forbidden"),
http_status_not_found(404, "Not Found"),
http_status_method_not_allowed(405, "Method Not Allowed"),
http_status_not_acceptable(406, "Not Acceptable"),
http_status_proxy_authentication_required(407, "Proxy Authentication Required"),
http_status_request_timeout(408, "Request Timeout"),
http_status_conflict(409, "Conflict"),
http_status_gone(410, "Gone"),
http_status_length_required(411, "Length Required"),
http_status_precondition_failed(412, "Precondition Failed"),
http_status_payload_too_large(413, "Payload Too Large"),
http_status_uri_too_long(414, "URI Too Long"),
http_status_unsupported_media_type(415, "Unsupported Media Type"),
http_status_requested_range_not_satisfiable(416, "Requested range not satisfiable"),
http_status_expectation_failed(417, "Expectation Failed"),
http_status_im_a_teapot(418, "I'm a teapot"),
http_status_unprocessable_entity(422, "Unprocessable Entity"),
http_status_locked(423, "Locked"),
http_status_failed_dependency(424, "Failed Dependency"),
http_status_upgrade_required(426, "Upgrade Required"),
http_status_precondition_required(428, "Precondition Required"),
http_status_too_many_requests(429, "Too Many Requests"),
http_status_request_header_fields_too_large(431, "Request Header Fields Too Large"),
// --- 5xx Server Error ---
http_status_internal_server_error(500, "系统错误"),
http_status_not_implemented(501, "Not Implemented"),
http_status_bad_gateway(502, "Bad Gateway"),
http_status_service_unavailable(503, "Service Unavailable"),
http_status_gateway_timeout(504, "Gateway Timeout"),
http_status_http_version_not_supported(505, "HTTP Version not supported"),
http_status_variant_also_negotiates(506, "Variant Also Negotiates"),
http_status_insufficient_storage(507, "Insufficient Storage"),
http_status_loop_detected(508, "Loop Detected"),
http_status_bandwidth_limit_exceeded(509, "Bandwidth Limit Exceeded"),
http_status_not_extended(510, "Not Extended"),
http_status_network_authentication_required(511, "Network Authentication Required"),
// --- 8xx common error ---
EXCEPTION(800, "exception"),
INVALID_PARAM(801, "invalid.param"),
INVALID_PRIVI(802, "invalid.privi"),
//1000以内是系统错误,
no_login(1000,"没有登录"),
config_error(1001,"参数配置表错误"),
user_exist(1002,"用户名已存在"),
userpwd_not_exist(1003,"用户名不存在或者密码错误"),
;
private static final Logger LOGGER = LoggerFactory.getLogger(ResultStatus.class);
private int code;
private String msg;
ResultStatus(int code, String msg){
this.code = code;
this.msg = msg;
}
public static int getCode(String define){
try {
return ResultStatus.valueOf(define).code;
} catch (IllegalArgumentException e) {
LOGGER.error("undefined error code: {}", define);
return FAIL.getErrorCode();
}
}
public static String getMsg(String define){
try {
return ResultStatus.valueOf(define).msg;
} catch (IllegalArgumentException e) {
LOGGER.error("undefined error code: {}", define);
return FAIL.getErrorMsg();
}
}
public static String getMsg(int code){
for(ResultStatus err : ResultStatus.values()){
if(err.code==code){
return err.msg;
}
}
return "errorCode not defined ";
}
public int getErrorCode(){
return code;
}
public String getErrorMsg(){
return msg;
}
}
参考文章
如何优雅的格式化接口: https://www.jianshu.com/p/12f470170b68.
什么是接口文档,如何写接口,有什么规范?:https://www.zhihu.com/question/52409287