Dawn-Api
[Toc]
说明
thinkphp5编写的restful风格的API,集API请求处理,权限认证,自动生成文档等功能;
restful风格处理请求
每个接口对于一个控制器,method对应[method]方法响应
权限认证
Basic,Oauth Client Credentials Grant
文档生成
简洁,优雅,不需要额外的文档工具;
安装
如果想在你的TP5项目中使用,那么可以直接使用
composer require liushoukun/dawn-api
如果是新项目先要创建tp5项目,然后再require
composer create-project topthink/think api --prefer-dist
composer require liushoukun/dawn-api
如果要使用生成文档 需要在public/static/ 下 安装hadmin
cd /public/static/
git clone https://git.oschina.net/liushoukun/hadmin.git
使用
新建demo 模块
创建业务基础类 Base 继承 ApiController
namespace app\demo\controller;
use DawnApi\facade\ApiController;
class Base extends ApiController
{
//是否开启授权认证
public $apiAuth = true;
}
?>
创建一个用户接口 User 继承 Base;
class User extends Base
添加资源路由
/v1/user
Route::group('v1',function (){
Route::resource('user','demo/User');
});
标识
请求类型
生成路由规则
对应操作方法(默认)
index
GET
v1/user
index
save
POST
v1/user
save
read
GET
v1/user/:id
read
update
PUT
v1/user/:id
update
delete
DELETE
v1/user/:id
delete
create
GET
v1/user/create
create
edit
GET
v1/user/:id/edit
edit
附加方法
如需要在添加一些额外的操作 如:发送验证码
在该类$extraActionList 属性添加方法
protected $extraActionList = ['sendCode']; //附加方法
之后注册路由
Route::group('v1',function (){
Route::any('user/sendCode','demo/User/sendCode');//需要在资源路由之前注册
Route::resource('user','demo/User');
});
跳过鉴权
如有有需要单操作跳过鉴权
在该类$skipAuthActionList 属性添加方法,即可跳过鉴权
protected $skipAuthActionList = ['sendCode']; //跳过鉴权的方法
返回处理
// 成功
return $this->sendSuccess($data = [], $message = 'success', $code = 200, $headers = [], $options = [])
// 错误
return $this->sendError($error = 400, $message = 'error', $code = 400, $data = [], $headers = [], $options = [])
// 重定向
return $this-> sendRedirect($url, $params = [], $code = 302, $with = [])
请求接口
开启授权认证
1.添加配置 认证总开关
'api_auth' => true, //是否开启授权认证
2.权限类 实现AuthContract 接口
authenticate 接口认证返回true则通过,否则不通过
getUser 获取用户信息,Api控制可以调用
self::$app['auth']->getUser();
/**
* 认证授权通过客户端信息和路由等
* 如果通过返回true
* @param Request $request
* @return bool
*/
public function authenticate(Request $request)
{
// TODO: Implement authenticate() method.
return true;
}
/**
* 获取用户信息 接口里可以直接获取用户信息
* @return mixed
*/
public function getUser()
{
return ['app_id'=>'111','name'=>'dawn-api'];
}
接口类开启授权认证
//是否开启授权认证
public $apiAuth = true;
配置(api_auth)
类($apiAuth)
效用
true
true
认证开启
true
false
认证关闭
false
false
认证关闭
false
true
认证关闭
配置验证类
简单实现了Basic & Oauth Client Credentials Grant认证
Basic
'auth_class' => \app\demo\auth\BasicAuth::class, //授权认证类
/v1/user?client_id=test&secret=test
OR
v1/user headers Basic
Oauth Client Credentials Grant
配置验证类
'auth_class' => \app\demo\auth\OauthAuth::class, //授权认证类
获取access_token
编写可访问的方法获取access_token
namespace app\demo\controller;
use app\demo\auth\OauthAuth;
use think\Request;
class Auth
{
public function accessToken()
{
$request = Request::instance();
$OauthAuth = new OauthAuth();
return $OauthAuth->accessToken($request);
}
}
配置路由
Route::any('accessToken','demo/auth/accessToken');//Oauth
按需改写获取客户端信息
请求获取
/accessToken?client_id=20882088&secret=nGk5R2wrnZqQ02bed29rjzax1QWRIu1O
或者
/accessToken
headers Basic MjA4ODIwODg6bkdrNVIyd3JuWnFRMDJiZWQyOXJqemF4MVFXUkl1MU8=
3.请求接口
/v1/user?access_token=cxXpnNIdf4aSIQFjR8NYH91Uwsg8jzMZ
快捷方式利用postman
自动生成文档
创建Doc文档显示控制器
wiki 继承 DawnApi\facade\Doc;
配置路由
// 文档
\DawnApi\route\DawnRoute::wiki();
可以改写该方法以存储数据获取,为了方便采用的是配置方式
tp5 增加额外配置 创建application/extra/api_doc.php 文件
return [
'1' => ['name' => '测试文档', 'id' => '1', 'parent' => '0', 'class'=>'','readme' =>''],//下面有子列表为一级目录
'2' => ['name' => '获取权限', 'id' => '2', 'parent' => '1', 'class'=>'','readme' => '/doc/md/auth.md'],//没有接口的文档,加载markdown文档
'3' => ['name' => '用户接口', 'id' => '3', 'parent' => '1', 'readme' => '','class'=>\app\test\controller\User::class],//User接口文档
];
参数
必须
备注
作用
name
true
接口列表名称
显示列表名称
id
true
主键
生成列表所用
parent
true
生成列表所用
class
true
接口位置
用于生成具体接口文档
readme
true
markdown
可以生成没有接口的文档,比如一些说明 module和controller为空,readme填文档路径
3.具体接口文档配置
接口描述部分(类文件的注释)
/**
* Class User
* @title 用户接口
* @url /v1/user
* @desc 有关于用户的接口
* @version 1.0
* @readme /doc/md/user.md
*/
class User extends Base{}
参数
必须
备注
作用
title
true
接口标题
显示列表名称
url
true
请求地址
用户显示
desc
true
接口描述
显示描述
version
false
版本号
版本号
readme
false
markdown文档
可以编写信息文档
具体接口文档
接口描述信息(注释填写)
/**
* @title 获取用户信息
* @desc 获取用户信息
* @readme /doc/md/method.md
*/
public function getResponse(\think\Request $request){}
参数
必须
备注
作用
title
true
接口标题
显示列表名称
desc
true
接口描述
显示描述
readme
false
markdown文档
可以编写信息文档
2.请求参数
/**
* 参数规则
* @name 字段名称
* @type 类型
* @require 是否必须
* @default 默认值
* @desc 说明
* @range 范围
* @return array
*/
public static function getRules()
{
$rules = [
'index' => [
],
'create' => [
'name' => ['name' => 'name', 'type' => 'string', 'require' => 'true', 'default' => '', 'desc' => '名称', 'range' => '',],
'age' => ['name' => 'age', 'type' => 'string', 'require' => 'true', 'default' => '', 'desc' => '年龄', 'range' => '',],
],
'sendCode' => [
'name' => ['name' => 'name', 'type' => 'string', 'require' => 'true', 'default' => '', 'desc' => '名称', 'range' => '',],
'age' => ['name' => 'age', 'type' => 'string', 'require' => 'true', 'default' => '', 'desc' => '年龄', 'range' => '',],
]
];
//可以合并公共参数
return $rules;
}
返回参数(注释填写)
* @return int id ID
* @return string username 错误信息
* @return int age 年龄
参数
必须
备注
第一个参数
true
类型
第二个参数
true
参数名
第三个参数
true
参数说明
类型填写规则
'string' => '字符串',
'int' => '整型',
'float' => '浮点型',
'boolean' => '布尔型',
'date' => '日期',
'array' => '数组',
'fixed' => '固定值',
'enum' => '枚举类型',
'object' => '对象',
整体效果
开发文档参考
开发工具推荐
IDE PHPSTORM
模拟请求 Postman