Laravel & Lumen RESTFul API 拡張パッケージ: Dingo API (1) -- インストールと設定

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 のプロバイダー配列にサービスプロバイダーを登録します:

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);

Facade

この拡張機能パッケージを処理するには 2 つのファサードがあり、任意の 1 つを追加できます:

DingoApiFacadeAPI
DingoApiFacadeRoute

2. 構成

基本的にすべての関数は事前に設定されているため、変更を加えることなく API の構築を開始できます。一部の小さな場所では、設定ファイル (Laravel) を公開する必要があります。 bootstrap/app.php での微調整や設定 (Lumen) には、AppServiceProvider の boot メソッドを使用することもできます。

標準ツリー

3 つの異なるツリーがあります: x、prs、および vnd 使用する標準ツリーは、開発しているプロジェクトによって異なります:

未登録のツリー (x) は主にローカルまたはプライベート環境で使用されます。
個人ツリー ( prs ) は主に非商用プロジェクトに使用されます
ベンダー ツリー ( vnd ) は主に公開および商用プロジェクトに使用されます

.env で設定できます:

API_STANDARDS_TREE=vnd

Subtype (サブタイプ)

サブタイプは通常、アプリケーションまたはプロジェクトの短縮名、または小文字です。 .env で設定することもできます:

API_SUBTYPE=myapp

プレフィックスとサブドメイン名

API を開発したことがあれば、ほとんどの API がサブドメイン名 (または特定のプレフィックス) の形式でサービスを提供することを知っているはずです。プレフィックスまたはサブドメイン名は必須であり、同時に存在するのは 1 つだけです。バージョン番号は通常、Accept ヘッダーを通じて処理されるため、プレフィックスまたはサブドメイン名としてバージョン番号を使用しないでください。

.env ファイルでプレフィックスを構成できます:

API_PREFIX=api

またはサブドメイン名:

API_DOMAIN=api.myapp.com

Version

ここでのバージョンは、バージョンが提供されていない場合に使用できる API のデフォルト バージョンを指します。または API ドキュメントを生成するときのデフォルト バージョンとして。

.env ファイルで設定できます:

API_VERSION=v1

Name

API の名前は、API ブループリント コマンドを使用してドキュメントを生成する場合にのみ使用されます。この名前は、次のような必要性を避けるためにデフォルト名として使用されます。ドキュメントを生成するときに名前を手動で指定します。

.env ファイルで設定できます:

API_NAME=My API

条件付きリクエスト

API リクエストをキャッシュするときにクライアント キャッシュ機能が使用されるため、条件付きリクエストはデフォルトで有効になります。これを設定ファイルで設定できます。 .env のオプション:

API_CONDITIONAL_REQUEST=false

Strict モード

Strict モードでは、クライアントは、構成ファイルで指定されているデフォルト バージョンの代わりに Accept ヘッダーを送信する必要があります。つまり、Web ブラウザーを介して API を参照することはできません。

Strict モードが有効で無効な Accept ヘッダーが使用されている場合、API は SymfonyComponentHttpKernelExceptionBadRequestHttpException 例外をスローします。

このオプションは .env で設定できます:

API_STRICT=false

認証プロバイダー

認証をより複雑に設定したい場合は、サービスプロバイダー (Laravel) で設定する必要があります。スタートアップ ファイル (Lumen) 設定:

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

スロットル/周波数制限

デフォルトの周波数スロットルは無効になっており、周波数制限のあるカスタム スロットルを登録するか、既存の認証および認証解除スロットルを使用できます。

より複雑な設定もサービス プロバイダーまたはスタートアップ ファイルで行う必要があります:

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

Response Converter

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