README

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

Installation

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

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.

ResponseHandlers

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().

Usage

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

allansun / openapi-runtime

Maintainers

Details

README

Installation

Basic concepts

ResponseHandlers

Usage

Projects using this lib