README

用于与从 OpenAPI 文档生成的其他 SDK 一起使用的运行时库。

安装

composer require allansun/openapi-runtime

您还需要一个 PSR-18 兼容的客户端，请参阅 https://docs.php-http.org/en/latest/clients.html

因此，您可以使用 Guzzle（或任何其他 PSR-18 兼容的客户端）

composer require php-http/guzzle7-adapter

基本概念

OpenAPI（以前称为 Swagger）通过提供以下内容定义了如何与 API 交互：

• API 端点 URI
• 输入有效载荷和输出响应（通常是 JSON 格式）

代码生成器可以通过解析 OpenAPI 文档生成有效代码。

我们试图提供有关您应该如何组织代码生成的指导。

响应处理器

此库提供的一个关键功能是将响应 JSON 转换为预定义的 PHP 对象。

通过调用 Client::configure()，您可以自定义自己的 ResponseHanderStack，它基本上是一个解析响应 JSON 的转换器堆栈。

您可以通过实现 ResponseHandlerInterface 创建自己的响应处理器。它是一个可调用的类，要么返回一个 Model，要么抛出一个 UndefinedResponseException，以便 ResponseHandlerStack 尝试下一个处理器。

默认情况下，我们提供了一个简单的 JSON 响应处理器（JsonPsrResponseHandler。它将尝试通过查找引用将响应解析为模型，这些引用在 ReponseTypes 中定义。请注意，您应该通过调用 ResponseTypes::setTypes() 设置您的响应引用。

用法

首先，您的生成的代码应该提供一种将响应引用解析到 ResponseTypes 的方法，或者您可以创建自己的 ResponseTypes 类并将其注入到 Handler，然后注入到 HandlerStack

<?php 
namespace App;

use OpenAPI\Runtime\ResponseTypes;
use OpenAPI\Runtime\ResponseHandler\JsonResponseHandler;
use OpenAPI\Runtime\ResponseHandlerStack\ResponseHandlerStack;

ResponseTypes::setTypes([
    'operation_id' =>[ // This should be unique to $ref as defined in the OpenAPI doc
        '200.' => 'YourGeneratedModelClass::class', // We add a dot after there HTTP status code to enforce string type
        '404.' => 'ErrorModel::class'
    ]
]);

class MyResponseHandlerStack extends ResponseHandlerStack
{
    public function __construct(?ResponseTypesInterface $responseTypes = null)
    {
        $handler = new JsonResponseHandler();
        if ($responseTypes) {
            $handler->setResponseTypes($responseTypes);
        }

        parent::__construct([$handler]);
    }
}  

然后在生成的代码中，您的 API 类 应该设置好 $responseHandlerStack 类名（实例将在 API 实例化时创建）

<?php
// Should be generated code here
namespace App\GeneratedCode;

use OpenAPI\Runtime\AbstractAPI;

class Customer extends AbstractAPI{
    protected static $responseHandlerStack = MyResponseHandlerStack::class;
    
    public function get($id)
    {
        return $this->request('operation_id', 'GET',"/customer/${id}");
    }
    
    public function post(array $payload)
    {
        return $this->request('post_operation_id','POST','/customer/',$payload);
    }
}

使用此库的项目

• allansun/openapi-code-generator
• bricre/royalmail-tracking-v2-sdk
• kubernetes/php-client