README

该组件读取以 OpenAPi/Swagger 2.0 编写的 API 服务描述，以序列化请求，并将响应解析为易于使用的模型结构。

依赖

该组件依赖于描述以下内容的知名接口：

• 使用 HTTPlug 提供的接口的 HTTP 客户端
• HTTP 消息，使用 PSR-7: HTTP 消息接口
• 缓存（用于缓存模式文件），使用 PSR-6: 缓存接口

安装

可以通过 composer 轻松安装此库。

composer require twentytwo-labs/api-service

使用

为了使用 API，您需要编写一个 API 服务描述。

目前，我们只支持 Swagger 文件，但我们计划在不久的将来支持 RAML 1.0 和 Api Blueprint。

对于独立项目，建议使用提供的构建器。

<?php
$apiService = TwentytwoLabs\Api\Service\ApiServiceBuilder::create()->build('file:///absolute/path/to/your/schema.json');

$operationId = 'getSomething';
$parameters = ['foo' => 'bar'];

// A Synchronous Request

/** @var \TwentytwoLabs\Api\Service\Resource\Resource $resource */
$resource = $apiService->call($operationId, $parameters);

// An Asynchronous Request

$promise = $apiService->callAsync($operationId, $parameters);
/** @var \TwentytwoLabs\Api\Service\Resource\Resource $resource */
$resource = $promise->wait();

重要：您必须在 Swagger 文件中为每个路径提供一个 operationId。

构建器依赖

您需要 HttPlug 提供的 HttpClient 适配器 和 HTTP 客户端发现服务 之一。

# install the discivery service
composer require php-http/discovery
# install one of the http client adapter (here, we use the guzzle6 adapter)
composer require php-http/guzzle6-adapter

构建器配置

构建器提供了一些额外的方法来调整您的 API 服务

• withCacheProvider(CacheItemPoolInterface $cacheProvider)

  使用 PSR-6: Cache Interface 缓存 API 服务描述

• withHttpClient(HttpClient $httpClient)

  提供一个实现 Http\Client\HttpClient 接口的 HttpClient。
  默认情况下，它将使用 Http\Discovery\HttpClientDiscovery::find() 方法

• withMessageFactory(MessageFactory $messageFactory)

  提供一个实现 Http\Message\MessageFactory 接口的 MessageFactory。
  默认情况下，它将使用 Http\Discovery\MessageFactoryDiscovery::find() 方法

• withUriFactory(UriFactory $uriFactory)

  提供一个实现 Http\Message\UriFactory 接口的 UriFactory。
  默认情况下，它将使用 Http\Discovery\UriFactory::find() 方法

• withSerializer(SerializerInterface $serializer)

  提供一个 Serializer。默认情况下，它将使用 Symfony Serializer。

• withEncoder(EncoderInterface $encoder)

  添加一个编码器来编码请求体和解码响应体。
  默认情况下，它将注册 Symfony 的 JsonEncoder 和 XmlEncoder。

• withPaginationProvider(PaginationProvider $paginatorProvide)

  当使用默认的 ResourceDenormalizer 时，您可以为 Collection 对象添加分页信息提供分页提供者。可用的实现可以在 src/Pagination/Provider 文件夹中找到。您可以通过实现 TwentytwoLabs\Api\Service\Pagination\Provider\PaginationProviderInterface 接口来创建自己的。

• withDenormalizer(NormalizerInterface $normalizer)

  添加一个用于反序列化 Response 解码体的反序列化器。
  默认情况下，它使用 TwentytwoLabs\Api\Service\Denormalizer\ResourceDenormalizer，将 Response 反序列化为 Resource 对象。一个 Resource 对象可以是一个 Item 或一个 Collection。

• withBaseUri($baseUri)

  提供您的 API 公开的基 URI。
  默认情况下，它将使用您的 API 服务描述中定义的 schemes 键和 host 键。

• disableRequestValidation()

  禁用对 API 服务描述的 Request 验证。默认启用。

• enableResponseValidation()

  启用对 API 服务描述的 Response 验证。默认禁用。

• returnResponse()

  当使用 ApiService 的 call() 和 callAsync() 方法时，返回 PSR-7 Response 而不是反序列化对象。

• setDebug($bool)

  启用调试模式。当启用时，如果使用 withCacheProvider(CacheItemPoolInterface $cacheProvider) 方法提供了缓存实现，它将立即过期模式缓存。