README

包已被废弃。请使用 JASPR Mapper 代替。

JSON API 标准规范实现

本项目目标是创建一个易于使用的库来实现 JSON API 规范。

整个项目处于开发初期。所以请不要犹豫，提供帮助。我对如何使这个库更定制化和友好持开放态度。

库只提供创建有效 JSON API 文档的包装器。控制器和响应由您负责。

问题

您可以通过发送电子邮件或在 gitlab 上创建问题。

安装

使用 Composer 安装库

composer require bednic/json-api

基本用法

为了简单起见，我们使用 $container 作为某些依赖提供者（依赖注入）。

MetadataRepository

首先我们需要创建 MetadataRepository。我们从 MetadataFactory 获取它。

<?php
/** @var $container Psr\Container\ContainerInterface */
// This is cache instance implements PSR SimpleCache
$cache = $container->get( Psr\SimpleCache\CacheInterface::class);
// This is AnnotationDriver or SchemaDriver, depends on your preferences
$driver = $container->get(\JSONAPI\Driver\Driver::class);
// Paths to your object representing resources
$paths = ['paths/to/your/resources','another/path'];
// Factory returns instance of MetadataRepository
$repository = JSONAPI\Factory\MetadataFactory::create(
            $paths,
            $cache,
            $driver
        );

DocumentBuilderFactory

选项

参数	默认值	描述
metadataRepository		MetadataRepository 的实例。
baseURL		API 所在的 URL。
maxIncludedItems	625	复合文档中包含的最大项目数。这防止了生成巨大的文档。
relationshipLimit	25	关系集合中包含的最大项目数。
relationshipData	true	切换是否关系应具有数据属性。
supportInclusion	true	切换是否服务器支持包含。
supportSort	true	切换是否服务器支持排序。
supportPagination	true	切换是否服务器支持分页。
paginationParser	null	负责解析分页的 PaginationParserInterface 实例。
filterParser	null	负责解析过滤器的 FilterParserInterface 实例。
logger	null	符合 PSR 的 LoggerInterface 实例。

<?php

// First we need DocumentBuilderFactory
// Let's get MetadataRepository from DI
/** @var $container Psr\Container\ContainerInterface */
$metadataRepository = $container->get(JSONAPI\Metadata\MetadataRepository::class);
$baseURL = "https:///"; // base URL where API lays
// You can initialize it by yourself
$dbf = new JSONAPI\Factory\DocumentBuilderFactory($metadataRepository, $baseURL);
// OR you can let DI make it for you
$dbf = $container->get(JSONAPI\Factory\DocumentBuilderFactory::class);
// We need PSR ServerRequestInterface instance
/** @var  $request Psr\Http\Message\ServerRequestInterface */
// Here we create instance of JSONAPI\Document\Builder
$builder = $dbf->new($request);
// Your object|objects
$data = new MyObject();
// $doc here is Document instance
$doc = $builder->setData($data)->build();

现在如果您将 $doc 编码为 JSON，您将得到完整的 JSON API 文档。关于 UriParser 的更多信息，请参阅这里

描述您的对象

您可以选择您想要描述对象元数据的方式。

使用注解

注意：如果您想使用注解，您必须在 MetadataFactory 中使用 AnnotationDriver。

示例

如您所见，设置资源对象相当简单。只需注解您的 getter 为 `#[Attribute] 或 #[Relationship]` 注解。

模式

关键部分是实现 Resource 接口。然后填充静态方法 getSchema。

注意：如果您想使用模式，您必须在 MetadataFactory 中使用 SchemaDriver。

示例

Open API 模式

本库对OAS提供了轻量级封装。它可以生成OAS v3.0.3的schema文件，以便您轻松地提供API文档。

基本示例

    $factory = new OpenAPISpecificationBuilder(
        $metadataRepository,
        'https://your.api.url'
    );

    $info = new Info('JSON:API OAS', '1.0.0');
    $info->setDescription('Test specification');
    $info->setContact(
        (new Contact())
            ->setName('Tomas Benedikt')
            ->setEmail('tomas.benedikt@gmail.com')
            ->setUrl('https://gitlab.com/bednic')
    );
    $info->setLicense(
        (new License('MIT'))
            ->setUrl('https://gitlab.com/bednic/json-api/-/blob/5.x/LICENSE')
    );
    $info->setTermsOfService('https://gitlab.com/bednic/json-api/-/blob/5.x/CONTRIBUTING.md');

    $oas = $factory->create($info);
    $oas->setExternalDocs(new ExternalDocumentation('https://gitlab.com/bednic/json-api/-/wikis/home'));

    $json = json_encode($oas);

UriParser

此对象与URL一起工作，并解析JSON API标准中描述的所需关键字。

选项

参数	默认值	描述
请求		PSR合规的ServerRequestInterface的实例。
metadataRepository		MetadataRepository 的实例。
baseURL		API 所在的 URL。
supportInclusion	true	切换是否服务器支持包含。
supportSort	true	切换是否服务器支持排序。
supportPagination	true	切换是否服务器支持分页。
paginationParser	null	负责解析分页的 PaginationParserInterface 实例。
filterParser	null	负责解析过滤器的 FilterParserInterface 实例。
logger	null	符合 PSR 的 LoggerInterface 实例。

路径接口

提供有关路径的信息，例如资源类型、资源ID、关系类型、是否为集合或关系。

字段集

请参阅：https://jsonapi.fullstack.org.cn/format/#fetching-sparse-fieldsets

过滤器

请参阅：https://jsonapi.fullstack.org.cn/format/#fetching-filtering

如上所述，规范对过滤器实现是中立的。因此，我从OData中创建了（或者说借鉴了）表达式过滤器。现在您可以使用如下这种格式

filter=stringProperty eq 'string' and contains(stringProperty,'asdf') and intProperty in (1,2,3) or boolProperty ne true and relation.property eq null

目前有两个ExpressionBuilder。

DoctrineQueryExpressionBuilder用于创建Doctrine QueryBuilder的表达式，如果您使用Doctrine并且需要更复杂的过滤，则它将自动提供。
DoctrineCriteriaExpressionBuilder与ArrayCollection或PersistentCollection（本库的依赖项）配合良好，因此它是默认的，您也可以使用它。但它只提供了一些基本表达式，如eq、ne等。但是，您不能通过关系属性过滤或使用某些函数或表达式。
ClosureExpressionBuilder从闭包创建表达式树，因此您根本不需要使用doctrine。

分页

请参阅：https://jsonapi.fullstack.org.cn/format/#fetching-pagination

我实现了三种分页技术中的两种。

LimitOffsetPagination
PagePagination
CursorPagination仅是抽象的，因为它需要不仅仅是几个数字，所以如果您想使用基于游标的分页，您必须自己实现它。

包含

请参阅：https://jsonapi.fullstack.org.cn/format/#fetching-includes

排序

请参阅：https://jsonapi.fullstack.org.cn/format/#fetching-sorting

bednic / json-api

维护者

详细信息