2.2. 配置

未匹配的标注
本文档最新版为 2.0.0,旧版本可能放弃维护,推荐阅读最新版!

Much of the package comes preconfigured so that you can start building your API as soon as possible. You can use your .env file to configure most of the package, however, some finer tuning of the package will require you to either publish the configuration file (Laravel) or configure it in bootstrap/app.php (Lumen). You may also use the boot method of your AppServiceProvider.

Important: If you're using Laravel 5 you must use either a published configuration file OR a service provider. Do not use the bootstrap/app.php file.

If you're using Laravel you can publish the configuration file with the following Artisan command:

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

Standards Tree

There's three different trees: x, prs, and vnd. The standards tree you use will depend upon the project you're developing.

  • The unregistered tree (x) is primarily meant for local or private environments.
  • The personal tree (prs) is primarily meant for projects that are not distributed commerically.
  • The vendor tree (vnd) is primarily meant for projects that are publically available and distributed.

Subtypes using the personal or vendor trees are technically meant to register with the IANA, but are not required to.

At the end of the day, if you aren't sure which to pick the x or unregistered tree is always a safe bet.

You can configure this in your .env file.

API_STANDARDS_TREE=vnd

Subtype

Your subtype is typically a short name of your application or project, all lowercase.

You can configure this in your .env file.

API_SUBTYPE=myapp

Prefixes and Subdomains

If you've ever worked with an API you'll know that most are served from either a subdomain or under a prefix. A prefix or subdomain is required, but only one. Avoid putting a version number as your prefix or subdomain as versioning is handled via the Accept header.

You can configure this in your .env file.

API_PREFIX=api

Or you can use a domain.

API_DOMAIN=api.myapp.com

Version

This version is the default version of your API and is used as a fallback in several circumstances whenever a version is not supplied. This version is also used
as a default version for when generating API documentation.

You can also configure this in your .env file.

API_VERSION=v1

Name

The name of your API is only used when you're generating documentation using the API Blueprint command. This name is used as a default
to avoid having to manually define the name whenever you generate documentation.

You can also configure this in your .env file.

API_NAME=My API

You may need to wrap the name in quotes.

API_NAME="My API"

Conditional Requests

By default conditional requests are enabled as it will utilize the clients caching capabilities when possible to cache API requests.

You can configure this in your .env file.

API_CONDITIONAL_REQUEST=false

Strict Mode

Strict mode will require clients to send the Accept header instead of defaulting to the version specified in the configuration file. This means you will not be able to browse the API through your web browser.

If strict mode is enabled and an invalid Accept header is used the API will throw an unhandled Symfony\Component\HttpKernel\Exception\BadRequestHttpException that should be you should handle appropriately.

You can configure this in your .env file.

API_STRICT=false

Authentication Providers

By default only basic authentication is enabled. Authentication is covered in more detail in a later chapter.

For more complex configuration you will need a service provider or bootstrap file.

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

Throttling / Rate Limiting

By default rate limiting is disabled. You can register your custom throttles with the rate limiter or use the existing authenticated and unauthenticated throttles.

For more complex configuration you will need a service provider or bootstrap file.

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

Response Transformer

Fractal is the default response transformer.

You can configure this in your .env. file, however, for more complex configuration you will need a service provider or bootstrap file.

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

Response Formats

The default response format is JSON and a JSON response format is registered by default.

You can configure the default response format in your .env file. Further response format configuration will need to take place in a published configuration file, a service provider, or in your bootstrap file.

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

Error Format

When the package encounters errors it will try to generate a generic error response instead of dumping exceptions to the user. The error format it uses can be configured to your liking.

You must configure this in a published configuration file or in your bootstrap file.

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

Debug Mode

Generic errors handled by the package include a debug key that will be populated with stack trace details when this is enabled.

You can configure this in your .env file.

API_DEBUG=true

← Installation | Creating API Endpoints →

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
《L05 电商实战》
从零开发一个电商项目,功能包括电商后台、商品 & SKU 管理、购物车、订单管理、支付宝支付、微信支付、订单退款流程、优惠券等
《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
讨论数量: 0
发起讨论 只看当前版本


暂无话题~