Skip to content
An OpenAPI/Swagger manipulation library
PHP
Branch: master
Clone or download
Latest commit cd886ab Jan 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Doc updates Jan 14, 2019
src Doc updates Jan 14, 2019
.gitignore Initial generation Oct 4, 2016
LICENSE.md Update and rename LICENSE to LICENSE.md Oct 4, 2016
README.md
composer.json Doc updates Jan 14, 2019

README.md

Strut

Yet another OpenAPI/Swagger manipulation library!

This library is almost 100% generated code by Gendarme. The reasoning behind this is that all the information required to manipulate a schema outlined in the specification.

Installation

via composer

composer require calcinai/strut

Usage

The test case for this is the OpenAPI petstore.

The library will deserialize an OpenAPI specification into native PHP objects, then serialize it back into its original form, with the only differences (sometimes) being the order of properties in objects (which is of no consequence).

Loading documents

$schema = json_decode(file_get_contents('http://petstore.swagger.io/v2/swagger.json'));
$openapi = \Calcinai\Strut\OpenAPI::create($schema);
print_r($swagger);

This will produce (snipped):

Calcinai\Strut\OpenAPI Object
(
 [data:protected] => Array
  (
   [openapi] => 3.0
   [info] => Calcinai\Strut\Definitions\Info Object
    (
     [data:protected] => Array
      (
       [version] => 1.0.0
       [title] => OpenAPI Petstore
       [license] => Calcinai\Strut\Definitions\License Object
        (
         [data:protected] => Array
          (
           [name] => MIT
          )

        )

      )

    )

   [servers] => Array
    (
     [0] => Calcinai\Strut\Definitions\Server Object
      (
       [data:protected] => Array
        (
         [url] => https://petstore.openapis.org/v1
         [description] => Development server
        )

      )

    )

   [paths] => Calcinai\Strut\Definitions\Paths Object
    (
     [data:protected] => Array
      (
       [/pets] => Calcinai\Strut\Definitions\PathItem Object
        (
         [data:protected] => Array
          (
           [get] => Calcinai\Strut\Definitions\Operation Object
            (
             [data:protected] => Array
              (
               [summary] => List all pets
               [operationId] => listPets
               [tags] => Array
                (
                 [0] => pets
                )

               [parameters] => Array
                (
                 [0] => Calcinai\Strut\Definitions\Parameter Object
                  (
                   [data:protected] => Array
                    (
                     [name] => limit
                     [in] => query
                     [description] => How many items to return at one time (max 100)
                     [required] =>
                     [schema] => Calcinai\Strut\Definitions\Schema Object
                      (
                       [data:protected] => Array
                        (
                         [type] => integer
                         [format] => int32
                        )

                      )

                    )

                  )

                )

               [responses] => Calcinai\Strut\Definitions\Responses Object
                (
                 [data:protected] => Array
                  (
                   [200] => Calcinai\Strut\Definitions\Response Object
                    (
                     [data:protected] => Array
                      (
                       [description] => An paged array of pets
                       [headers] => Calcinai\Strut\Definitions\HeadersOrReferences Object
                        (
                         [data:protected] => Array
                          (
                           [x-next] => Calcinai\Strut\Definitions\Header Object
                            (
                             [data:protected] => Array
                              (
                               [schema] => Calcinai\Strut\Definitions\Schema Object
                                (
                                 [data:protected] => Array
                                  (
                                   [type] => string
                                  )

                                )

                               [description] => A link to the next page of responses
                              )

                            )

                          )

                        )

                       [content] => Calcinai\Strut\Definitions\MediaTypes Object
                        (
                         [data:protected] => Array
                          (
                           [application/json] => Calcinai\Strut\Definitions\MediaType Object
                            (
                             [data:protected] => Array
                              (
                               [schema] => Calcinai\Strut\Definitions\Reference Object
                                (
                                 [data:protected] => Array
                                  (
                                   [$ref] => #/components/schemas/Pets
                                  )

                                )

                              )

                            )

                          )

                        )

                      )

                    )

...

Creating and modifying documents

The following is an example of how that schema would be programatically generated:

$pet = Schema::create()
    ->addRequired('id')
    ->addRequired('name')
    ->setProperties(Properties::create()
        ->set('id', Schema::create()
            ->setType('integer')
            ->setFormat('int64')
        )
        ->set('name', Schema::create()
            ->setType('string')
        )
        ->set('tag', Schema::create()
            ->setType('string')
        )
    );

$pets = Schema::create()
    ->setType('array')
    ->setItems($pet);


$error = Schema::create()
    ->addRequired('code')
    ->addRequired('message')
    ->setProperties(Properties::create()
        ->set('code', Schema::create()
            ->setType('integer')
            ->setFormat('int32')
        )
        ->set('error', Schema::create()
            ->setType('string')
        )
    );


$schema = OpenAPI::create()
    ->setInfo(
        Info::create()
            ->setTitle('Swagger Petstore')
            ->setVersion('1.0.0')
            ->setLicense(
                License::create()
                    ->setName('MIT')
            )
    )
    ->addServer(\Calcinai\Strut\Definitions\Server::create()->setUrl('petstore.swagger.io'))
    ->setPaths(Paths::create()
        ->set('/pets', PathItem::create()
            ->setGet(Operation::create()
                ->setSummary('List all pets')
                ->setOperationId('listPets')
                ->addTag('pets')
                ->setResponses(Responses::create()
                    ->set('200', Response::create()
                        ->setDescription('A paged array of pets')
                    )
                    ->set('default', Response::create()
                        ->setDescription('Unexpected error')
                    )
                )
            )
        )
    )
    ->setComponents(\Calcinai\Strut\Definitions\Components::create()
        ->setSchemas(\Calcinai\Strut\Definitions\SchemasOrReferences::create()
            ->set('Pet', $pet)
            ->set('Pets', $pets)
            ->set('Error', $error)
        )
    );

echo json_encode($schema, JSON_PRETTY_PRINT);

This will output:

{
    "info": {
        "title": "Swagger Petstore",
        "version": "1.0.0",
        "license": {
            "name": "MIT"
        }
    },
    "servers": [
        {
            "url": "petstore.swagger.io"
        }
    ],
    "paths": {
        "\/pets": {
            "get": {
                "summary": "List all pets",
                "operationId": "listPets",
                "tags": [
                    "pets"
                ],
                "responses": {
                    "200": {
                        "description": "A paged array of pets"
                    },
                    "default": {
                        "description": "Unexpected error"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Pet": {
                "required": [
                    "id",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "format": "int64"
                    },
                    "name": {
                        "type": "string"
                    },
                    "tag": {
                        "type": "string"
                    }
                }
            },
            "Pets": {
                "type": "array",
                "items": {
                    "required": [
                        "id",
                        "name"
                    ],
                    "properties": {
                        "id": {
                            "type": "integer",
                            "format": "int64"
                        },
                        "name": {
                            "type": "string"
                        },
                        "tag": {
                            "type": "string"
                        }
                    }
                }
            },
            "Error": {
                "required": [
                    "code",
                    "message"
                ],
                "properties": {
                    "code": {
                        "type": "integer",
                        "format": "int32"
                    },
                    "error": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

This isn't the full example, but it gives an idea of the structure.

Contributing

I'd love feedback and/or contributions, but they will probably need to target the generation library. Head to Gendarme if this sounds like you. Basic command for generating this library is

./bin/gendarme generate --namespace "Calcinai\Strut" --root-class Swagger  ../strut/lib/schema.json ../strut/src/
You can’t perform that action at this time.