README

在Hyperf中构建功能丰富且符合标准的API。

此包是从cloudcreativity/laravel-json-api迁移过来的。

此包提供了将符合JSON API规范的API添加到您的应用程序所需的所有功能。对规范的支持非常广泛，包括

• 获取资源
• 获取关系
• 包含相关资源（复合文档）
• 稀疏字段集。
• 排序。
• 分页。
• 过滤
• 创建资源。
• 更新资源。
• 更新关系。
• 删除资源。
• 验证
  • JSON API文档；以及
  • 查询参数。

以下附加功能也得到支持

• 全面支持Hyperf模型资源，具有以下功能：
  • 包含相关资源时自动预加载。
  • 易于使用的关系端点。
  • 软删除和恢复模型资源。
  • 基于页面和游标的分页。
• 异步处理。
• 支持API中的多种媒体类型。
• 生成添加资源到API所需的所有类。

什么是JSON API？

来自jsonapi.org

如果您曾与团队争论JSON响应的格式，JSON API将是您的抗争论利器。

通过遵循共享约定，您可以提高生产力，利用通用工具，并专注于真正重要的事情：您的应用程序。围绕JSON API构建的客户端能够利用其功能，有效地缓存响应，有时甚至完全消除网络请求。

有关规范的全部信息以及示例，请参阅http://jsonapi.org。

文档

@todo

许可

Apache许可证（版本2.0）。请参阅许可文件获取更多信息。

安装

composer require hyperf-ext/json-api

配置

发布配置文件

php bin/hyperf.php vendor:publish hyperf-ext/json-api

默认配置

<?php

return [
    'apis' => [
        'v1' => [
            /*
             |--------------------------------------------------------------------------
             | Root Namespace
             |--------------------------------------------------------------------------
             |
             | The root namespace for JSON API classes for this API.
             |
             | The `by-resource` setting determines how your units are organised within
             | your root namespace.
             |
             | - true:
             |   - e.g. App\JsonApi\Posts\{Adapter, Schema, Validators}
             |   - e.g. App\JsonApi\Comments\{Adapter, Schema, Validators}
             | - false:
             |   - e.g. App\JsonApi\Adapters\PostAdapter, CommentAdapter}
             |   - e.g. App\JsonApi\Schemas\{PostSchema, CommentSchema}
             |   - e.g. App\JsonApi\Validators\{PostValidator, CommentValidator}
             |
             */
            'namespace' => 'App\JsonApi\V1',
            'by-resource' => true,
    
            /*
             |--------------------------------------------------------------------------
             | Model
             |--------------------------------------------------------------------------
             |
             | Whether your JSON API resources predominantly relate to Eloquent models.
             | This is used by the package's generators.
             |
             | You can override the setting here when running a generator. If the
             | setting here is `true` running a generator with `--no-model` will
             | override it; if the setting is `false`, then `--model` is the override.
             |
             */
            'use-model' => true,
            'model-namespace' => 'App\Model',
    
            /*
             |--------------------------------------------------------------------------
             | Resources
             |--------------------------------------------------------------------------
             |
             | Here you map the list of JSON API resources in your API to the actual
             | record (model/entity) classes they relate to.
             |
             | For example, if you had a `posts` JSON API resource, that related to
             | an Eloquent model `App\Post`, your mapping would be:
             |
             | `'posts' => \App\Model\Post::class`
             */
            'resources' => [
                //'posts' => \App\Model\Post::class,
            ],
    
            /*
             |--------------------------------------------------------------------------
             | URL
             |--------------------------------------------------------------------------
             |
             | The API's url, made up of a host, URL namespace and route name prefix.
             |
             | If a JSON API is handling an inbound request, the host will always be
             | detected from the inbound HTTP request. In other circumstances
             | (e.g. broadcasting), the host will be taken from the setting here.
             | If it is `null`, the `app.url` config setting is used as the default.
             | If you set `host` to `false`, the host will never be appended to URLs
             | for inbound requests.
             |
             | The name setting is the prefix for route names within this API.
             |
             */
            'url' => [
                'host' => null,
                'namespace' => '/v1',
                'name' => 'v1:',
            ],
    
            /*
             |--------------------------------------------------------------------------
             | Controllers
             |--------------------------------------------------------------------------
             |
             | The default JSON API controller wraps write operations in transactions.
             | You can customise the connection for the transaction here. Or if you
             | want to turn transactions off, set `transactions` to `false`.
             |
             */
            'controllers' => [
                'transactions' => true,
                'connection' => null,
            ],
    
            /*
             |--------------------------------------------------------------------------
             | Jobs
             |--------------------------------------------------------------------------
             |
             | Defines settings for the asynchronous processing feature. We recommend
             | referring to the documentation on asynchronous processing if you are
             | using this feature.
             |
             | Note that if you use a different model class, it must implement the
             | asynchronous process interface.
             |
             */
            'jobs' => [
                'resource' => 'queue-jobs',
                'model' => \HyperfExt\JsonApi\Queue\ClientJob::class,
            ],
        ],
    ],

    /*
     |--------------------------------------------------------------------------
     | Resolver
     |--------------------------------------------------------------------------
     |
     | The API's resolver is the class that works out the fully qualified
     | class name of adapters, schemas, authorizers and validators for your
     | resource types. We recommend using our default implementation but you
     | can override it here if desired.
     */
    'resolver' => \HyperfExt\JsonApi\Resolver\ResolverFactory::class,

    /*
     |--------------------------------------------------------------------------
     | Encoding Media Types
     |--------------------------------------------------------------------------
     |
     | This defines the JSON API encoding used for particular media
     | types supported by your API. This array can contain either
     | media types as values, or can be keyed by a media type with the value
     | being the options that are passed to the `json_encode` method.
     |
     | These values are also used for Content Negotiation. If a client requests
     | via the HTTP Accept header a media type that is not listed here,
     | a 406 Not Acceptable response will be sent.
     |
     | If you want to support media types that do not return responses with JSON
     | API encoded data, you can do this at runtime. Refer to the
     | Content Negotiation chapter in the docs for details.
     |
     */
    'encoding' => [
        'application/vnd.api+json',
    ],

    /*
     |--------------------------------------------------------------------------
     | Decoding Media Types
     |--------------------------------------------------------------------------
     |
     | This defines the media types that your API can receive from clients.
     | This array is keyed by expected media types, with the value being the
     | service binding that decodes the media type.
     |
     | These values are also used for Content Negotiation. If a client sends
     | a content type not listed here, it will receive a
     | 415 Unsupported Media Type response.
     |
     | Decoders can also be calculated at runtime, and/or you can add support
     | for media types for specific resources or requests. Refer to the
     | Content Negotiation chapter in the docs for details.
     |
     */
    'decoding' => [
        'application/vnd.api+json',
    ],

    /*
     |--------------------------------------------------------------------------
     | Providers
     |--------------------------------------------------------------------------
     |
     | Providers allow vendor packages to include resources in your API. E.g.
     | a Shopping Cart vendor package might define the `orders` and `payments`
     | JSON API resources.
     |
     | A package author will define a provider class in their package that you
     | can add here. E.g. for our shopping cart example, the provider could be
     | `Vendor\ShoppingCart\JsonApi\ResourceProvider`.
     |
     */
    'providers' => [],

    /*
     |--------------------------------------------------------------------------
     | Logger
     |--------------------------------------------------------------------------
     |
     */
    'logger' => [
        'enabled' => false,
        'name' => 'json-api',
        'group' => 'default',
    ],
];