Runtime library to be used with other SDK generated from OpenAPI docs

3.2.3 2022-06-26 11:26 UTC


Latest Stable Version Total Downloads License codecov

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

So either use Guzzle (or any other PSR-18 compatible clients)

composer require php-http/guzzle7-adapter

Basic concepts

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

namespace App;

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

    '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) {


Then in the generated code you API class should set have the $responseHandlerStack class name ready (a instance will be created on API instantiation)

// 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);

Projects using this lib