README

Installation

composer require pmbservices/swaggerclient

How it works

SwaggerClient provide a base class PMBServices\Swagger\SwaggerClient for loading Swagger json definition file and create a proxy to the REST webservice using the magic PHP method __call.

You can extend this base class to use a specific implementation in a software.

For now, two extended class are provided :

PMBServices\SwaggerClient\SwaggerClaroline for the LMS Claroline
PMBServices\SwaggerClient\SwaggerDolibarr for the CRM Dolibarr

SwaggerClient parse all the paths in the swagger definition file, extract mandatory parameters in each path e.g. {param}, then the others parameters of type body or query denpending of the HTTP method.

Then you can call any webservice method by the following naming convention :

[protocol][pathInCamelCase]()

For example, if a swagger server provides the path GET /order/{id} the name of the method would be getOrderId()

Passing arguments

For passing arguments to method call, just pass an Array : ["parameter name" => value, ...]

For example : $swaggerclient->getOrderId(["id"=>1234,"limit"=>100])

Return

The return is a PHP object parsed with the Json response of the webservice. We don't yet handle XML, files or stream.

Extend SwaggerClient

To extend the class SwaggerClient for a specific server, you have to define the folowing properties of the class in the constructor :

Imagine a swagger webservice at https://myserver/mysoftware/api/swagger.json

baseUrl : the base of the URL of the webservice, e.g. https://myserver
swaggerPath : the path form the baseUrl to the swagger json file, e.g. /mysoftware/api/swagger.json

then you must set the default HTTP options for the Guzzle HTTP Client with the method setOption, for example the header for the key. You can add any other option allowed by the Guzzle HTTP client.

When the swagger definition file is parsed, the baseUrl and basePath are replaced with the ones sent by swagger.

Full example

<?php
namespace PMBServices\SwaggerClient;

use PMBServices\Swagger\SwaggerClient;

class SwaggerDolibarr extends SwaggerClient {
    public function __construct($baseUrl,$basePath,$key="") {
        $this->baseUrl=$baseUrl;
        $this->swaggerPath="$basePath/api/index.php/explorer/swagger.json";
        if ($key) $this->setOption([
            "headers"=>[
                "DOLAPIKEY" => $key
            ]
        ]);
        parent::__construct();
    }
}

For Dolibarr, the path of the API is always /api/index.php/explorer/swagger.json in the case we consider the first argument as the base host and the basePath as the path until /api... Note the setOption to pass the key in the header DOLAPIKEY.

Using it !

My Dolibarr is hosted at https://myserver/doliprod

$doli=new PMBServices\SwaggerClient\SwaggerDolibarr("https://myserver","/doliprod","1zxky");
$doli->setOption(["cert"=>"cert.pem","ssl_key"=>"cert.key"]);
$doli->connect();
$orders=$doli->getOrder();
var_dump($orders);

The $doli->setOption(["cert"=>"cert.pem","ssl_key"=>"cert.key"]); is because I have a strong authentification with a SSL client certificate. Then you must call the method $doli->connect() to fetch the swagger definition file and parse it to determine the paths. The json swagger definition file is then cached in the directory cache for quicker future instantiation.

pmbservices / swaggerclient

Maintainers

Details