Laravel Api 开发系列 - Dingo API 的使用

源码

使用 Dingo Api

本文使用的数据库与基础篇相同，故不再重复说明。

初始化

安装

$ composer require dingo/api:1.0.x@dev

注册

/config/app.php
'providers' => [
    Dingo\Api\Provider\LaravelServiceProvider::class,
],

为了能够自定义配置，首先需要执行

$ php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"
Copied File [/vendor/dingo/api/config/api.php] To [/config/api.php]
Publishing complete.

可以看到多了个 api.php 的配置文件，我们就可以在 .env 中对其进行配置，一些常用的配置项:

/.env
API_STANDARDS_TREE=vnd  # 公开的及商业项目用 vnd
API_SUBTYPE=api-demo  # 项目简称
API_PREFIX=api  # 前缀
API_VERSION=v1  # 不提供版本时使用的版本号
API_NAME="Laravel Api Demo"  # 使用 API Blueprint 命令生成文档的时候才用到
API_STRICT=false # Strict 模式要求客户端发送 Accept 头而不是默认在配置文件中指定的版本，这意味着你不能通过Web浏览器浏览API
API_DEFAULT_FORMAT=json 
API_DEBUG=true # 开启 debug 模式

创建一个基本的端点(路由在 api 中的叫法）测试下是否配置成功

/routes/api.php
$api = app('Dingo\Api\Routing\Router');
$api->version('v1', function ($api) {

    $api->get('test', function () {
        return 'It is ok';
    });

});

访问 /api/test，返回 It is ok。

使用

Dingo 的用法与之前的自定义 api 用法类似，甚至更加简单。首先定义路由

/routes/api.php
$api = app('Dingo\Api\Routing\Router');
$api->version('v1', function ($api) {

    $api->group(['namespace' => 'App\Api\Controllers'], function ($api) {
        $api->resource('lessons','LessonController');
    });

});

如果要查看路由，需要使用

$ php artisan api:routes

创建控制器 - 需要使用 Helpers 这个 trait。

/app/Api/Controllers/LessonController.php
<?php
namespace App\Api\Controllers;

use App\Api\Transformers\LessonTransformer;
use App\Http\Controllers\Controller;
use App\Lesson;
use Dingo\Api\Routing\Helpers;

class LessonController extends Controller
{    
    use Helpers;

    public function index()
    {    
        $lessons = Lesson::all();
        // collection 用于响应一个集合，同时绑定一个 Transformer 来格式化数据
        return $this->collection($lessons, new LessonTransformer());
    }

    public function show($id)
    {    
        // 尽管我们返回的不是 json，但是 dingo 会自动进行转化
        return Lesson::findOrFail($id);
    }
}

创建对应的 LessonTransformer

/app/Api/Transformers/LessonTransformer.php
<?php
namespace App\Api\Transformers;

use App\Lesson;
use League\Fractal\TransformerAbstract;

class LessonTransformer extends TransformerAbstract
{
    public function transform(Lesson $lesson)
    {
        return [
            'title'   => $lesson['title'],
            'content' => $lesson['body'],
            'is_free' => (bool) $lesson['free']
        ];
    }
}

访问 api/lessons/3,结果如下

可以看出，Dingo 自动将响应的数据转化为了 json，不过我们还需要将其格式化

public function show($id)
{    
    $lesson = Lesson::findOrFail($id);
    return $this->response->item($lesson, new LessonTransformer());
}

现在，就可以得到格式化的数据了

跟 Laravel 类似，也可以使用分页

public function index()
{    
    $lessons = Lesson::paginate(15);
    return $this->response->paginator($lessons, new LessonTransformer());
}

将会返回 15 条信息以及分页信息

当请求出错时，Dingo 会自动帮我们进行处理

也可以自定义

public function show($id)
{    
    $lesson = Lesson::find($id);
    if(!$lesson){
        return $this->response->errorNotFound("错误的 id");
    }
    return $this->response->item($lesson, new LessonTransformer());
}

结果如下

结合简单的认证

我们可以在 Api 中加入自带的验证功能，比如 HTTP 基础认证。首先，创建一个测试用户

$ php artisan tinker
>>> $user = new \App\User();
>>> $user->name = "zen"
>>> $user->email = "[e-mail]"
>>> $user->password = bcrypt("123456")
>>> $user->save()
=> true

在控制器中加入 Laravel 自带的中间件即可

public function __construct()
{
    $this->middleware('auth.basic');
}

现在访问时会提示输入用户名和密码，这里的用户名指的是邮箱