sammy / specification
Api Server
1
2018-04-01 13:05 UTC
Requires
- php: >=7.0
This package is not auto-updated.
Last update: 2024-10-01 04:29:11 UTC
README
[TOC]
1. 部署说明
现有API基于laravel框架开发,本次介绍也针对laravel。可根据文档自行调整,以适用其他框架下使用
安装
composer require sammy/specification dev-master
1.1. 数据库相关
执行数据库迁移 php artisan migrate
或者手动执行如下SQL语句
CREATE TABLE `prefix_apps` ( `id` INT(10) NOT NULL AUTO_INCREMENT COMMENT '自增长', `app_id` VARCHAR(60) NOT NULL COMMENT 'appid', `app_secret` VARCHAR(100) NOT NULL COMMENT '密钥', `app_name` VARCHAR(200) NOT NULL COMMENT 'app名称', `app_desc` TEXT COMMENT '描述', `status` TINYINT(2) DEFAULT '0' COMMENT '生效状态', `created_at` INT(10) NOT NULL DEFAULT '0' COMMENT '创建时间', `updated_at` INT(10) NOT NULL DEFAULT '0' COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `app_id` (`app_id`), KEY `status` (`status`) ) ENGINE=INNODB DEFAULT CHARSET=utf8 COMMENT='应用表';
1.2. 目录相关
2. API文档及开发规范
2.1. API调用协议
2.1.1. 请求方式
请求方式:
POST
/GET
2.1.2. 公共参数
2.1.3. 业务参数
API调用除了必须包含公共参数外,如果API本身有业务级的参数也必须传入,每个API的业务级参数请考API文档说明。
2.1.4. 签名规则
- 对所有API请求参数(包括公共参数和请求参数,但除去
sign
参数),根据参数名称的ASCII码表的顺序排序。如:foo=1, bar=2, foo_bar=3, foobar=4
排序后的顺序是bar=2, foo=1, foo_bar=3, foobar=4
。 - 将排序好的参数名和参数值拼装在一起,根据上面的示例得到的结果为:bar2foo1foo_bar3foobar4。
- 把拼装好的字符串采用utf-8编码,使用签名算法对编码后的字节流进行摘要。如果使用
MD5
算法,则需要在拼装的字符串前后加上app的secret
后,再进行摘要,如:md5(secret+bar2foo1foo_bar3foobar4+secret) - 将摘要得到的字节结果使用大写表示
2.1.5. 返回结果
// 成功 { "status": true, "code": "200", "msg": "成功", "data": { "time": "2016-08-02 12:07:09" } } // 失败 { "status": false, "code": "1001", "msg": "[app_id]缺失" }
2.2. API开发规范
2.2.1. API接口命名规范(method)
2.2.1. 错误码
错误码配置:
vendor/sammy/specification/Error.php
命名规范:
现有错误码:
2.2.3. API DEMO 示例
示例代码:##
class TestController extends Controller
{
public function index(Request $request, Server $server){
return $server->run(function()use($request){
return [
'status' => true,
'code' => '200',
'data' => [
date('Y-m-d H:i:s')
]
];
});
}
}