1 Star 0 Fork 61

superdreams / restfulapi-tp5

forked from liushoukun / restfulapi-tp5 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README

Dawn-Api

Latest Stable Version Total Downloads Latest Unstable Version License Monthly Downloads [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

使用

  1. 新建demo 模块
  2. 创建业务基础类 Base 继承 ApiController
<?php
   namespace app\demo\controller;


   use DawnApi\facade\ApiController;
   class Base extends ApiController
   {

    //是否开启授权认证
    public    $apiAuth = true;

   }
?>
  1. 创建一个用户接口 User 继承 Base;
class User extends Base
  1. 添加资源路由

/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. 请求接口

开启授权认证

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'];
    }
  1. 接口类开启授权认证
//是否开启授权认证
public    $apiAuth = true;
配置(api_auth) 类($apiAuth) 效用
true true 认证开启
true false 认证关闭
false false 认证关闭
false true 认证关闭
  1. 配置验证类

简单实现了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
  1. 配置验证类
   'auth_class' => \app\demo\auth\OauthAuth::class, //授权认证类
  1. 获取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=

accessToken

3.请求接口 /v1/user?access_token=cxXpnNIdf4aSIQFjR8NYH91Uwsg8jzMZ

accessToken

快捷方式利用postman accessToken accessToken accessToken

自动生成文档

  1. 创建Doc文档显示控制器 wiki 继承 DawnApi\facade\Doc;

  2. 配置路由

// 文档
\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接口文档
];

wiki

参数 必须 备注 作用
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文档 可以编写信息文档

ClassDoc

  • 具体接口文档
  1. 接口描述信息(注释填写)
       /**
        * @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;

    }

data

  1. 返回参数(注释填写)
     * @return int id ID
     * @return string username 错误信息
     * @return int age 年龄
参数 必须 备注
第一个参数 true 类型
第二个参数 true 参数名
第三个参数 true 参数说明

类型填写规则

'string'    => '字符串',
'int'       => '整型',
'float'     => '浮点型',
'boolean'   => '布尔型',
'date'      => '日期',
'array'     => '数组',
'fixed'     => '固定值',
'enum'      => '枚举类型',
'object'    => '对象',

return

整体效果 all all all

开发文档参考

开发工具推荐

  • IDE PHPSTORM
  • 模拟请求 Postman

空文件

简介

thinkphp5编写的restful风格的API,集API请求处理,权限认证,自动生成文档等功能; 展开 收起
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
PHP
1
https://gitee.com/superdream2018/restfulapi-tp5.git
git@gitee.com:superdream2018/restfulapi-tp5.git
superdream2018
restfulapi-tp5
restfulapi-tp5
master

搜索帮助

14c37bed 8189591 565d56ea 8189591