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 = "ihuangmx@qq.com"
>>> $user->password = bcrypt("123456")
>>> $user->save()
=> true

在控制器中加入 Laravel 自帶的中間件便可

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

如今訪問時會提示輸入用戶名和密碼，這裏的用戶名指的是郵箱