接口规范文档总结、接口管理工具推荐、如何写出完美的接口

写在前面：这是我最近整理的接口规范文档，无规矩不成方圆，为了app开发人员与后台接口开发人员更好的配合，我特意整理了这么一篇文档供大家参考学习，如有意见请在评论区留言谢谢。因部分内容涉及公司代码，我对本文档略有删减。

接口规范说起来大，其实也就那么几个部分，接口规范、接口管理工具、接口文档编写、开发文档编写。以下将详细介绍，下面进入正文：

接口规范文档

具体内容如下：

一：协议规范

二：域名规范

三：版本控制规范

四：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/”]

重要的事情说三遍。

根据业务需求，可以在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 : 每页数量。

2. 列表接口选传字段。

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

后台需进行非空非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是一个可视化接口管理工具通过分析接口结构，动态生成模拟数据，校验真实接口正确性，围绕接口定义，通过一系列自动化工具提升我们的协作效率。

完本。

如果有什么建议或者意见，请在邮箱或者评论区留言，谢谢。

我的邮箱：zhangtaoandroid@163.com

接口规范文档总结、接口管理工具推荐、如何写出完美的接口相关推荐

有哪些文档和知识管理工具推荐？ - 易智编译EaseEditing
以下是一些常用的文档和知识管理工具推荐: Evernote: Evernote是一款强大的笔记和知识管理工具,可以帮助您保存和组织文档.笔记.图片和网页剪辑,并支持跨设备同步和搜索功能. Micros ...
如何写出完美的接口：接口规范定义、接口管理工具推荐
无规矩不成方圆,为了开发人员间更好的配合,我特意整理了这么一篇文档供大家参考学习,如有意见.见解,请在评论区留言探讨. 接口规范说起来大,其实也就那么几个部分,接口规范.接口管理工具.接口文 ...
NotionAI - 文档领域的ChatGPT，一款 AI 加持的在线文档编辑和管理工具
简介 NotionAI - 文档领域的ChatGPT,一款 AI 加持的在线文档编辑和管理工具作为国际领先的在线文档编辑和管理工具,Notion受到了广大用户的欢迎,尤其是程序员们.它不仅支持笔记. ...
史上最全的团队文档协作及管理工具盘点，看看哪款适合你
转载地址:http://geek.csdn.net/news/detail/130184 现如今,越来越多的人开始认识到知识管理的重要性,然而对文档知识库的管理本身却是件极其耗费时间精力的事情.这时, ...
jstree中文api文档_还在用 Swagger（丝袜哥）生成接口文档？我推荐你试试它。。。...
作者:小鱼儿511https://blog.csdn.net/dongbeiou/article/details/106771453JApiDocs是一个无需额外注解.开箱即用的SpringBoot接 ...
写在国产接口管理工具ApiPost 5.2.5发布后的一些话
好多年没写文章了,突然想写些什么东西的时候,却卡顿如狗,瞬时自身的内存和CPU均红色报警,不知道从何处下笔. 遥想以前学生时代,本人还是语文老师口中的才子,曾多次向校报投稿,如今竟沦落到这个境地. 与 ...
组件分享之后端组件——阿里妈妈前端团队出品的开源接口管理工具RAP第二代rap2-delos...
组件分享之后端组件--阿里妈妈前端团队出品的开源接口管理工具RAP第二代rap2-delos 背景近期正在探索前端.后端.系统端各类常用组件与工具,对其一些常见的组件进行再次整理一下,形成标准化组件 ...
ApiPost与PostMan，你可以任选一款不错的接口管理工具
我们都知道在一个团队中是由很多角色组成的,例如:业务.产品.设计.前端.后端.测试.每个角色各司其职,一起合作完成项目的交付. 而前端与后端的沟通则是需要通过一个统一的文件进行沟通交流,即通过接口文档 ...
Java后端接口自动生成神器 -- EasyYapi插件（Yapi接口管理工具在IDEA里的插件）
Java后端接口自动生成神器 – EasyYapi插件(Yapi接口管理工具在IDEA里的插件) 一.先看效果 1.生成yapi文档的效果 2.生成postman格式数据并导入接口测试类后的效果(如p ...

接口规范文档总结、接口管理工具推荐、如何写出完美的接口

接口规范文档总结、接口管理工具推荐、如何写出完美的接口相关推荐

最新文章

热门文章