• 内容协商
• 多认证适配器
• 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']);
});

上面的认证配置 好像应该改成

1. 'auth' => [  
2.     'basic' => function($app){  
3.         return new Dingo\Api\Auth\Provider\Basic($app['auth']);  
4.     },  
5.     'jwt' => function($app){  
6.         return new Dingo\Api\Auth\Provider\JWT($app['Tymon\JWTAuth\JWTAuth']);  
7.     }  
8. ],  

默认频率限制是被禁用的，你可以注册自定义的带有频率限制的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