接口规范文档总结

作者: 码课sir | 来源:发表于2018-09-03 08:34 被阅读111次

    接口规范文档

    具体内容如下:

    一:协议规范

    二:域名规范

    三:版本控制规范

    四:API路径规范

    五:API命名规范

    六:请求参数规范

    七:列表请求特殊规范

    八:返回数据规范

    九:接口文档规范

    十:接口管理工具使用教程

    参与编写 更新日期 版本 备注
    AbyssKitty 2018/04/06 V1.1.0

    V1.1.0更新日志:

    1. 新增协议规范、域名规范、版本控制规范、列表特殊规范。

    2. 更新接口管理工具使用教程。

    3. 美化排版。

    正文:

    一:协议规范

    为进一步确保数据交互安全。正式地址(生产地址)必须遵循HTTPS协议。

    二:域名规范

    每个项目要有且仅有一个自己唯一的域名+端口。在项目配置文件中要添加静态变量专门进行存储。

    如果一个域名满足不了要求,那么就需要再添加一个。

    格式规范如下:

    (java)public static final String URL_BASE = “https://127.0.0.1:8080/”;

    (java)public static final String URL_BASE_SUB = “https://192.168.0.1:8080/”;

    必须以https开头,并以“/”结尾。

    三:API路径规范

    作为接口路径,为了和其他路径完美区分,必须在路径中添加api目录

    格式规范如下:

    (java)public static final String URL_API = “api/”;

    (PHP)php目录是加index.php/api/

    必须以字母开头,并以“/”结尾。

    四:版本控制规范

    项目正式上线后,正式版本要确定接口版本、并备份接口代码。

    为方便管理,需要在接口路径中加入版本号信息。

    格式规范如下:

    (java)public static final String URL_VERSION =”v1/”;

    必须以字母开头,并以“/”结尾。

    更新版本后可以使用v2 v3等、依次递加。

    五:API命名规范

    根据二:域名规范、三:API路径规范、四:版本控制规范。项目中必须在配置文件中增加BaseUrl静态常量。值=三个相加。

    格式规范如下:

    (java)public static final String BASEURL=URL_BASE+URL_API+URL_VERSION;

    具体代码如下:

    BASEURL = [“https://127.0.0.1:8080/api/v1/”]

    BASEURL = [“https://127.0.0.1:8080/api/v1/”]

    BASEURL = [“https://127.0.0.1:8080/api/v1/”]

    重要的事情说三遍。

    根据业务需求,可以在v1版本文件夹里创建,一个或者多个接口文件。

    一个的规范:

    https://127.0.0.1:8080/api/v1/getBanner

    这就是一个获取banner的接口。

    多个的规范是根据业务需求来区分:

    https://127.0.0.1:8080/api/v1/home/getBanner

    https://127.0.0.1:8080/api/v1/user/userLogin

    新建user文件,里面存放用户级别的操作:如登陆、注册、修改密码等等。

    新建sms文件,里面存放对短信的接口操作:如发送验证码、验证手机号等等。

    所以,接口方法文件必须要有自己的规范,命名必须统一使用驼峰命名法或者下划线拼接命名法。举个栗子:(upperCamelCase)(upper_camel_case)。所有接口命名方式,必须遵循如下规范。

    (1)新增方法:如新增一个地址、新增一个联系人。

    命名规范:

    必须以“add”为前缀。例如addAddress

    事例地址:https://127.0.0.1:8080/api/v1/addAddress

    (2)删除方法:如删除一个地址。

    命名规范:

    必须以“delete”为前缀。例如deleteAddress

    事例地址:https://127.0.0.1:8080/api/v1/deleteAddress

    (3)修改方法:如修改一个地址。

    命名规范:

    必须以“updata”为前缀。例如updataAddress

    事例地址:https://127.0.0.1:8080/api/v1/updataAddress

    (4)获取方法:如获取一个地址。

    命名规范:

    必须以“get”为前缀。例如getAddress

    事例地址:https://127.0.0.1:8080/api/v1/getAddress

    (5)获取列表方法:如获取一个地址列表。

    命名规范:

    必须以“get”为前缀、“List”为后缀。例如getAddressList

    事例地址:https://127.0.0.1:8080/api/v1/getAddressList

    其他规范:

    发送验证码使用‘send’为前缀、保存一个数据以‘save’为前缀、上传图片以‘uploadImage’为名称等等。

    具体地址就等于BASEURL+“address/getAddressList”)

    目的:一目了然、降低维护成本。

    六:请求参数规范

    请求方式:公共数据使用get方式请求,私有数据使用post方式请求。尽量全部是用post。

    请求头:请求头根据项目需求添加配置参数。如:accept=‘application/json

    ’等。请求头根据项目需求可以要求传入用户token、app名称版本、唯一验签码等加密数据。

    ​ 请求参数:

    根据数据库字段进行命名、保持一致最省事。

    七:列表请求特殊规范

    列表请求,请求参数规范,必须传参:页数和每页个数的字段。并可包含查询等信息。

    1. 列表接口必传字段(分页、使用小写字母)。

    **page **:页数,从1开始。例如:{ “page”: 1 }

    **subnumber **: 每页数量。

    1. 列表接口选传字段。

    只要是列表接口、一般情况下都会存在检索条件,例如淘宝商品检索。检索条件为选填。

    后台需进行非空非null判断,选传字段为空为null默认查询全部。有值则需要接收,并进行sql查询。

    规范事例:

    普通列表接口:https://127.0.0.1:8080/api/v1/getBannerList

    (不传page、后台默认返回全部数据)

    banner接口不需要使用检索条件)

    需检索列表接口:https://127.0.0.1:8080/api/v1/getOrderList

    (不传page、后台默认返回全部数据)

    Order订单接口需要检索条件,不传就不检索,只进行分页查询)

    (如果有 time price等检索条件,不传就不检索,传了就进行条件查询,并返回相应数据)

    八:返回数据规范

    注:列表数据返回,没有特殊情况的条件下,必须最新数据在上面,依次排序。

    返回事例:

    {

    "list":[],

    "object":{}, //"object":""

    "status":"SUCCESS",

    "message":"我是提示消息",

    ** ...**

    "page":1,

    "subnumber":10,

    }

    必选-命名规范:驼峰命名法。

    必选-新增键值规则:名字对应固定的格式(list就是数组[])。

    举个栗子:比如一个"list":[]满足不了需求,那么可以新增一个"map":[]。

    比如一个"object":{"name":"小明"}满足不了需求,那么可以新增一个"details":{"name":"小红"}。名字对应固定的格式,数组就是数组、实体类就是实体类、字段就是字段。不能data在这个接口返回的是实体类、另一个接口又返回数组了。需要特别注意。

    必选-list:list列表(数组)为空时显示[]。

    必选-object:实体数据,json键值对。

    必选-status:状态信息=SUCCESS、ERROR等静态变量。

    必选-message:提示消息。(加载成功、)

    可选-page:页数(分页查新时使用、显示第几页从一开始)。

    可选-subnumber:每页的格式(分页查询时使用、显示当前页的个数)。

    九:接口文档规范

    接口文档需要包含以下部分:

    文档名称。

    版本号。

    编写人。

    编写、修改日期。

    baseUrl地址。

    更新日志。

    接口详情。(详情规范如下)

    接口详情编辑规范:

    一个完整的接口需要由以下几部分组成

    1.请求地址 例如:https://127.0.0.1:8080/xxx/xxx/xxx

    2.请求方式 例如:POST、GET等

    3.请求参数 例如:传 id:“1”,name:“小明”

    4.返回参数 例如:{ json... } 【参考上面的接口规范】

    5.返回事例 例如:{ json... }

    十:接口管理工具使用教程

    接口管理工具有很多,例如RAP、eolinker等等。

    接口管理工具基本的作用都是用来管理接口的。这里简单介绍eolinker的使用方法。

    使用方法步骤:

    创建接口管理项目。

    邀请开发者同事加入。

    编写接口(接口地址、请求参数及备注、请求方式、返回参数及备注、返回事例、在线测试接口)。

    开发者使用接口。

    过程中灵活配合,接口可以灵活更新。

    完成项目后可以导出接口文档。

    附件:XXX接口管理工具使用教程点击进入eolinker使用教程

    RAP的特色:

    RAP是一个GUI的WEB接口管理工具。在RAP中,您可定义接口的URL、请求&响应细节格式等等。通过分析这些数据,RAP提供MOCK服务、测试服务等自动化工具。RAP同时提供大量企业级功能,帮助企业和团队高效的工作。

    在前后端分离的开发模式下,我们通常需要定义一份接口文档来规范接口的具体信息。如一个请求的地址、有几个参数、参数名称及类型含义等等。RAP 首先方便团队录入、查看和管理这些接口文档,并通过分析结构化的文档数据,重复利用并生成自测数据、提供自测控制台等等... 大幅度提升开发效率。

    强大的GUI工具 给力的用户体验,你将会爱上使用RAP来管理您的API文档。

    完善的MOCK服务 文档定义好的瞬间,所有接口已经准备就绪。有了MockJS,无论您的业务模型有多复杂,它都能很好的满足。

    庞大的用户群 RAP在阿里巴巴有200多个大型项目在使用,也有许多著名的公司、开源人士在使用。RAP跟随这些业务的成行而成长,专注细节,把握质量,经得住考验。

    免费 + 专业的技术支持 RAP是免费的,而且你的技术咨询都将在24小时内得到答复。大多数情况,在1小时内会得到答复。

    RAP是一个可视化接口管理工具 通过分析接口结构,动态生成模拟数据,校验真实接口正确性, 围绕接口定义,通过一系列自动化工具提升我们的协作效率。


    完本。

    相关文章

      网友评论

        本文标题:接口规范文档总结

        本文链接:https://www.haomeiwen.com/subject/bizvwftx.html