Laravel & Lumen RESTFul API 扩展包：Dingo API（一） —— 安装配置篇

转自：http://laravelacademy.org/post/3822.html

Dingo API 为开发者提供了一整套工具以便帮助你轻松、快捷的构建自己的API。这些工具包括：

内容协商

多认证适配器

API版本

频率限制

响应转化和格式化

错误及异常处理

内部请求

API文档

1、安装

安装该扩展包之前需要保证已经安装以下程序：

Laravel 5.1+
或 Lumen 5.1+

PHP 5.5.9+

然后通过如下Composer命令安装扩展包：

composer require dingo/api:1.0.x@dev

安装完成后的操作取决于你使用的是哪个框架。

Laravel

在

config/app.php

中注册服务提供者到

providers

数组：

Dingo\Api\Provider\LaravelServiceProvider::class

如果你想要自定义扩展包配置可以将其发布到

config

目录下：

php artisan vendor:publish --provider="Dingo\Api\Provider\LaravelServiceProvider"

Lumen

打开

bootstrap/app.php

注册需要的服务提供者：

$app->register(Dingo\Api\Provider\LumenServiceProvider::class);

门面

有两个门面来处理这个扩展包，你可以添加任意一个：

Dingo\Api\Facade\API

Dingo\Api\Facade\Route

2、配置

基本上所有功能都已经预先配置好，所以不需要什么改动就可以开始构建API，你可以使用

.env

文件实现大部分配置，对于一些细小的地方需要发布配置文件（Laravel）进行微调或者在

bootstrap/app.php

中配置（Lumen），你还可以使用

AppServiceProvider

的

boot

方法。

标准树

有三个不同的树：

x

、

prs

和

vnd

，你使用的标准树取决于你所开发的项目：

未注册的树（

x

）主要用于本地或私有环境

个人树（

prs

）主要用于非商业销售的项目

供应商树（

vnd

）主要用于公开的以及商业销售的项目

你可以在

.env

中配置：

API_STANDARDS_TREE=vnd

子类型（Subtype）

子类型通常是应用或项目的简称，或小写格式。你也可以在

.env

中配置：

API_SUBTYPE=myapp

前缀和子域名

如果你曾经开发过API应该知道大部分API都是以子域名（或某个前缀）形式提供服务，前缀或子域名是必须的，并且同时只有一个，不要讲版本号作为前缀或子域名，因为版本号通常通过

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

Strict模式

Strict模式要求客户端发送

Accept

头而不是默认在配置文件中指定的版本，这意味着你不能通过Web浏览器浏览API。

如果Strict模式开启并且使用了无效的

Accept

头，API会抛出一个

Symfony\Component\HttpKernel\Exception\BadRequestHttpException

异常。

你可以在

.env

中配置这个选项：

API_STRICT=false

认证提供者

默认只开启了

basic

认证，如果要对认证进行更复杂的配置，需要在服务提供者（Laravel）或启动文件（Lumen）设置：

$app['Dingo\Api\Auth\Auth']->extend('oauth', function ($app) {
   return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']);
});

Throttling/频率限制

默认频率限制是被禁用的，你可以注册自定义的带有频率限制的throttle或者使用已经存在的认证及取消认证throttle。

要进行更加复杂的配置同样需要在服务提供者或启动文件中操作：

$app['Dingo\Api\Http\RateLimit\Handler']->extend(function ($app) {
    return new Dingo\Api\Http\RateLimit\Throttle\Authenticated;
});

响应转化器

Fractal

是默认的响应转化器。你可以在

.env

中配置，但如果要实现更加复杂的配置还是需要在服务提供者或启动文件操作：

$app['Dingo\Api\Transformer\Factory']->setAdapter(function ($app) {
    $fractal = new League\Fractal\Manager;

    $fractal->setSerializer(new League\Fractal\Serializer\JsonApiSerializer);

    return new Dingo\Api\Transformer\Adapter\Fractal($fractal);
});

响应格式

默认的响应格式是JSON，你可以在配置文件

.env

中配置默认的响应格式：

API_DEFAULT_FORMAT=json

更加高级的格式配置需要发布配置文件到

config

目录或者在服务提供者及启动文件中操作：

Dingo\Api\Http\Response::addFormatter('json', new Dingo\Api\Http\Response\Format\Jsonp);

错误格式

如果扩展包遇到错误将会尝试生成错误响应而不是将异常抛给用户，错误格式可以进行自定义配置。该配置必须在

config

目录下对应的配置文件（Laravel）或启动文件（Lumen）中实现：

$app['Dingo\Api\Exception\Handler']->setErrorFormat([
    'error' => [
        'message' => ':message',
        'errors' => ':errors',
        'code' => ':code',
        'status_code' => ':status_code',
        'debug' => ':debug'
    ]
]);

调试模式

如果开启了调试模式的话吗，生成的错误信息会被扩展包放到

debug

键中，并与堆栈跟踪信息一起显示出来。

你可以在配置文件

.env

中配置：

API_DEBUG=true