loco/swizzle

Build Guzzle service descriptions from Swagger compliant APIs

2.0.2 2019-11-19 17:23 UTC

Requires

• php: >=5.5
• ext-json: *
• guzzlehttp/guzzle-services: ^1.1
• monolog/monolog: 1.*

Requires (Dev)

• phpunit/phpunit: ^4.0 || ^5.0

MIT

• Tim Whitlock
• Alexandr Zolotukhin

• api
• Guzzle
• swagger

README

Build Guzzle service descriptions from Swagger compliant APIs.

What?

• Guzzle is a framework for building HTTP clients in PHP.
• Swagger is a specification for describing RESTful services.

Although Guzzle's service descriptions are heavily inspiried by the Swagger spec, they are different enough that we need something to bridge the divide.

Swizzle crawls JSON Swagger docs (such as ours) and transforms them into a compatible schema for use with guzzle/guzzle-services.

Important! This library is for use with v1.2 of the Swagger specification which is obsolete.

Installation

Installation is via Composer.

Add the latest stable version of loco/swizzle to your project's composer.json file as follows:

{
  "require": {
    "loco/swizzle": "~2.0"
  }
}

If you want to install straight from Github you'll have to write your own autoloader for now.

Usage

Basic usage is to configure, build and export - as follows:

$builder = new Loco\Utils\Swizzle\Swizzle( 'foo', 'Foo API' );
$builder->build('http://foo.bar/path/to/swagger/docs/');
// Serialize Guzzle service config to json
file_put_contents('/path/to/config.json', $builder->toJson());
// Now use saved config.json in your project/library to create Guzzle service.

More advanced usage includes registering custom Guzzle classes for commands and responses. See example directory for fuller, working examples.

Build the PHP API documentation with apigen using apigen -c apigen.yml

Limitations

This library supports only version 1.2 of the old Swagger specification. We developed this very quickly for our own needs, and haven't kept up with the newer OpenAPI project.