allansun / openapi-runtime
Runtime library to be used with other SDK generated from OpenAPI docs
Installs: 5 188
Dependents: 119
Suggesters: 0
Security: 0
Stars: 1
Watchers: 6
Forks: 1
Open Issues: 0
Requires
- php: ^7.4|^8.0
- ext-json: *
- php-http/discovery: ^1.14
- php-http/message-factory: ^1.0
- phpdocumentor/reflection-docblock: ^5.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0
- psr/log: 1.*|2.*|3.*
- symfony/property-info: ^4|^5|^6
Requires (Dev)
- guzzlehttp/guzzle: ^7.4
- php-http/httplug-bundle: ^1.25
- phpspec/prophecy: ^1.12
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ~9
- squizlabs/php_codesniffer: ^3.6
- symfony/http-client: ^v4|^v5|^v6
- vimeo/psalm: ^4.17
Suggests
- guzzlehttp/guzzle: ^7
- monolog/monolog: ^2
- symfony/http-client: ^v5.2.6
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); } }