接口规范说起来大,其实也就那么几个部分,接口规范、接口管理工具、接口文档编写、开发文档编写。以下将详细介绍,下面进入正文:
接口规范文档
具体内容如下:
一:协议规范
二:域名规范
三:版本控制规范
四: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版本文件夹里创建,一个或者多个接口文件。
一个的规范:
这就是一个获取banner的接口。
多个的规范是根据业务需求来区分:
新建user文件,里面存放用户级别的操作:如登陆、注册、修改密码等等。
新建sms文件,里面存放对短信的接口操作:如发送验证码、验证手机号等等。
所以,接口方法文件必须要有自己的规范,命名必须统一使用驼峰命名法或者下划线拼接命名法。举个栗子:(upperCamelCase)(upper_camel_case)。所有接口命名方式,必须遵循如下规范。
(1)新增方法:如新增一个地址、新增一个联系人。
命名规范:
必须以“add”为前缀。例如addAddress
(2)删除方法:如删除一个地址。
命名规范:
必须以“delete”为前缀。例如deleteAddress
(3)修改方法:如修改一个地址。
命名规范:
必须以“updata”为前缀。例如updataAddress
(4)获取方法:如获取一个地址。
命名规范:
必须以“get”为前缀。例如getAddress
(5)获取列表方法:如获取一个地址列表。
命名规范:
必须以“get”为前缀、“List”为后缀。例如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查询。
规范事例:
(不传page、后台默认返回全部数据)
(banner接口不需要使用检索条件)
(不传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的使用方法。
使用方法步骤:
创建接口管理项目。
邀请开发者同事加入。
编写接口(接口地址、请求参数及备注、请求方式、返回参数及备注、返回事例、在线测试接口)。
开发者使用接口。
过程中灵活配合,接口可以灵活更新。
完成项目后可以导出接口文档。
1. 查询指定项目属性
接口功能
获取制定项目的分类信息
URL
http://www.api.com/index.php
支持格式
JSON
HTTP请求方式
GET
请求参数
参数 必选 类型 说明
name ture string 请求的项目名
type true int 请求项目的类型。1:类型一;2:类型二 。
返回字段
返回字段 字段类型 说明
status int 返回结果状态。0:正常;1:错误。
company string 所属公司名
category string 所属类型
接口示例
地址:http://www.api.com/index.php?name=”可口可乐”&type=1
{
“statue”: 0,
“company”: “可口可乐”,
“category”: “饮料”,
}
1
2
3
4
5
markdown源码如下:
目录
1\. 查询指定项目属性接口
—
**1\. 查询指定项目属性**
###### 接口功能
> 获取制定项目的分类信息
###### URL
> [http://www.api.com/index.php](www.api.com/index.php)
###### 支持格式
> JSON
###### HTTP请求方式
> GET
###### 请求参数
> |参数|必选|类型|说明|
|:—– |:——-|:—–|—– |
|name |ture |string|请求的项目名 |
|type |true |int |请求项目的类型。1:类型一;2:类型二 。|
###### 返回字段
> |返回字段|字段类型|说明 |
|:—– |:——|:—————————– |
|status |int |返回结果状态。0:正常;1:错误。 |
|company |string | 所属公司名 |
|category |string |所属类型 |
###### 接口示例
> 地址:[http://www.api.com/index.php?name=”可口可乐”&type=1](http://www.api.com/index.php?name=”可口可乐”&type=1)
“` javascript
{
“statue”: 0,
“company”: “可口可乐”,
“category”: “饮料”,
}
———————