开源软件名称:restfulapi-tp5
开源软件地址:https://gitee.com/liushoukun/restfulapi-tp5
开源软件介绍:
Dawn-Api[Toc] 说明thinkphp5编写的restful风格的API,集API请求处理,权限认证,自动生成文档等功能; 每个接口对于一个控制器,method对应[method]方法响应
Basic,Oauth Client Credentials Grant
简洁,优雅,不需要额外的文档工具;
安装composer require liushoukun/dawn-api - 如果是新项目先要创建tp5项目,然后再require
composer create-project topthink/think api --prefer-distcomposer require liushoukun/dawn-api - 如果要使用生成文档 需要在public/static/ 下 安装hadmin
cd /public/static/git clone https://git.oschina.net/liushoukun/hadmin.git 使用- 新建demo 模块
- 创建业务基础类 Base 继承 ApiController
<?php namespace app\demo\controller; use DawnApi\facade\ApiController; class Base extends ApiController { //是否开启授权认证 public $apiAuth = true; }?> - 创建一个用户接口 User 继承 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 接口 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认证
'auth_class' => \app\demo\auth\BasicAuth::class, //授权认证类 /v1/user?client_id=test&secret=testORv1/user headers Basic - Oauth Client Credentials Grant
- 配置验证类
'auth_class' => \app\demo\auth\OauthAuth::class, //授权认证类 - 获取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或者/accessTokenheaders 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' => '对象', 整体效果 开发文档参考开发工具推荐 |
请发表评论