Runtime library to be used with other SDK generated from OpenAPI docs.
composer require allansun/openapi-runtime
You will also need a PSR-18 compatible client see https://docs.php-http.org/en/latest/clients.html
So either use Guzzle (or any other PSR-18 compatible clients)
composer require php-http/guzzle7-adapter
OpenAPI (formally Swagger) defines how API should be interacted with by giving
- API endpoint URI
- input payload and output response (normally in JSON format)
Code generators can generate valid code by parsing the OpenAPI doc.
We try to provide a guidance on how you should organize your code generation.
One key function this lib provides is to transform response JSON into predefined PHP objects.
By calling Client::configure() you can customize your own ResponseHanderStack , which basically is a stack of transformers to parse the response JSON.
You can create your own ResponseHandler by implementing the ResponseHandlerInterface. It is simply an invokable class either returns a Model or throws an UndefinedResponseException so the ResponseHandlerStack can try next handler.
By default, we provide a simple JSON response handler( JsonPsrResponseHandler. It will try to parse the response into a model by looking into reference, which is defined in ReponseTypes. Be aware you should set up your response references by calling ResponseTypes::setTypes().
First your generated code should provide a way to parse response references into ResponseTypes, or you can create your own ResponseTypes class and inject into a Handler then into a 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]);
}
}
Then in the generated code you API class should set have the $responseHandlerStack class name ready (a instance will be created on API instantiation)
<?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);
}
}