dingo API+laravel的初步体验
参考网址:https://learnku.com/docs/dingo-api/2.0.0/Installation/1443
php 版本:php^7.0
1.安装插件
1.1安装插件
composer require dingo/api
或者在项目中修改composer.json
文件 并且运行 composer update
"require": {
"dingo/api": "^2.2"
}
laravel
使用以下命令可以发布API的配置文件到config文件下:
php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"
2、配置信息
standards Tree 标准树
这有三个不同的树: x,prs 和 vnd。你使用的标准树需要取决于你开发的项目
- 未注册的树(x)主要表示本地和私有环境
- 私有树(prs)主要表示没有商业发布的项目
- 供应商树(vnd)主要表示公开发布的项目
子类型使用私有和供应商树在技术上意味着在 IANA 上注册,但是并不强制要求。
最后,如果你不确定该如何选择,x 树或者说未注册树都是安全的。
你可以配置在 .env 文件中。
API_STANDARDS_TREE=vnd
子类型
子类型通常是应用程序或项目的短名称,都是小写的。
你可以在你的 .env 文件中配置这个。
API_SUBTYPE=myapp
响应格式
默认的响应格式是 JSON,并有一个 JSON 响应格式是被默认注册。
你可以在 .env 文件中配置默认的响应格式。更进一步的响应格式配置需要在一个 published 的配置文件,服务提供器,或是 bootstrap 文件中。
API_DEFAULT_FORMAT=json
Dingo\Api\Http\Response::addFormatter('json', new Dingo\Api\Http\Response\Format\Jsonp);
错误模式
当包遇到错误时,它会尝试生成一个通用的错误响应,而不是将异常转储给用户。 它使用的错误格式可以根据自己的喜好进行配置。
您必须在已发布的配置文件或引导程序文件中对其进行配置。
$app['Dingo\Api\Exception\Handler']->setErrorFormat([
'error' => [
'message' => ':message',
'errors' => ':errors',
'code' => ':code',
'status_code' => ':status_code',
'debug' => ':debug'
]
]);
调试模式
该包处理的通用错误包括一个 debug 键,当启用这个键时,将会填充堆栈跟踪详细信息。
你可以在 .env 文件中配置它。
API_DEBUG=TRUE;
前缀和子域
如果你曾经使用过 API 你就会知道大多数服务都来自子域或前缀。前缀或子域是必须的,但只需要一个。请避免使用版本号作为你的前缀或子域,因为版本控制是通过 header 头 Accept 处理的。
你可以在你的 .env 文件中配置这个。
API_PREFIX=api
可以使用域名
API_DOMAIN=api.myapp.com
版本号
这个版本号是你的 API 的默认版本号,并且会在一些未提供版本号的情况下作为回调的默认值使用。在生成 API 文档时也会使用这个版本号作为默认值。
你可以在你的 .env 文件中这么配置它。
API_VERSION=v1
名称
你的 API 的名称只会在你使用 API Blueprint 命令生成文档的时候使用。使用此名称可以避免你每次生成文档的时候都必须手动定义名称。
你可以在你的 .env 文件中这么配置它。
API_NAME="My API"
条件请求
『条件请求』默认为开启状态,这有利于客户端的缓存机制在可能的情况下缓存 API 请求。
你可以在你的 .env 文件中将其配置为关闭:
API_CONDITIONAL_REQUEST=false
严格模式严格模式要求客户端发送 Accept 头,代替配置文件中配置的默认版本。这意味着你将不能通过浏览器直接访问你的 API。
如果开启严格模式,发送非法的 Acceept 标头会抛出一个未处理的异常 Symfony\Component\HttpKernel\Exception\BadRequestHttpException ,你需要自己处理这个异常。
你可以在你的 .env 文件中配置。
API_STRICT=false
认证服务
默认的只有 basic 认证是开启的。在后面的章节中会有详细的介绍。
更多复杂的配置你需要配置在一个 service provider 或者启动文件中。
$app['Dingo\Api\Auth\Auth']->extend('oauth', function ($app) {
return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']);
});
访问节流
默认情况下『访问节流』是关闭的。你可以注册你自定义的阀门,或者使用已经存在的认证的和非认证的阀门。
更多复杂的配置你需要配置在一个 service provider 或者启动文件中。
$app['Dingo\Api\Http\RateLimit\Handler']->extend(function ($app) {
return new Dingo\Api\Http\RateLimit\Throttle\Authenticated;
});
路由设置
// dingo/api 将会使用专属的路由实例 要创建端点 必须获得一个api路由的实例
$api=app('Dingo\Api\Routing\Router');
// version 定义一个版本分组 有利于后续
//
//为相同端点新增多版本支持
//[]可以传递一个属性数组 将此组视为特定框架的标准组
$api->version('v1',function ($api){
//需要为控制器添加说明完整的命名空间
$api->group(['namespace'=>'App\Http\Controllers\Api'],function ($api){
//嵌套常规组以进一步定制某些端点 这里的role:admin 是需要设置的暂时不知道如何设置
// $api->group(['middleware'=>['role:admin']],function (){
//可用接口
$api->get('/users','AdminApiController@show');
//});
});
});
使用php artisan make:route
查看已经设置的路由
响应
响应生成器
响应生成器提供了一个流畅的接口去方便的建立一个更定制化的响应。响应的生成器通常是与 transformer 相结合。
要利用响应生成器,你的控制器需要使用 Dingo\Api\Routing\Helpers trait。为了在你的控制器里保持引入和使用这个 trait,你可以创建一个基础控制器,然后你的所有的 API 控制器都继承它。
php artisan make:controller Api/BaseController
响应一个元素
php artisan make:controller Api/AdminApiController
在AdminApiController 中写以下代码
use App\Admin\Manager;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class AdminApiController extends BaseController
{
//展示
public function show(Request $request){
$res=Manager::where('status','1')->limit(10)->get();
return $this->response->array($res->toArray());
}
}
如果使用
使用postman 访问 :
laravel使用transformer转化器和分页