pupaxxo/swagger-builder

Compile Swagger2.0 JSON using PHP.

2.0.2 2017-11-13 09:35 UTC

Requires (Dev)

• phpunit/phpunit: ^6.0

MIT

• Samuel Davis
• Andrea Ruggiero

README

Now you can write your Swagger API documentation in JSON, YAML, or PHP!

Do you find the Swagger config very hard to write? Well (with an informative IDE) this should make it easier.

Usage Note:

Fields Swagger requires appear in constructors, optional fields are set with specific setter methods. There's type hinting all over the place!

Example: Swagger Petstore (Simple)

Swagger

A valid Swagger object requires the Swagger version, an Info object and at least 1 Path.

$swagger = (new Swagger('2.0', $info, $paths))
    ->setHost('petstore.swagger.io')
    ->setBasePath('/api')
    ->setSchemes([Scheme::HTTP])
    ->setConsumedMimes([Mime::APP_JSON])
    ->setProducedMimes([Mime::APP_JSON]);

Info

A valid Info object requires the application name and version.

// (optional) contact from the example
$contact = (new Contact())
    ->setName('Swagger API team')
    ->setEmail('[e-mail]')
    ->setUrl('http://swagger.io');

// (optional) license from the example
$license = (new License('MIT'))
    ->setUrl('http://opensource.org/licenses/MIT');

// The Info object is what we really need
$info = (new Info('Swagger Petstore (Simple)', '1.0.0'))
    ->setDescription('A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification')
    ->setTermsOfService('http://helloreverb.com/terms/')
    ->setContact($contact)
    ->setLicense($license);

Paths

A valid Path object requires a route and at least 1 Operation.

$paths = [
    new Path('/pets', $operations),
];

Operations

A valid Operation object requires an HTTP verb and at least 1 example Response.

$addPet = (new Operation(Verb::POST, $responses))
    ->setDescription('Creates a new pet in the store. Duplicates are allowed')
    ->setOperationId('addPet')
    ->setProducedMimes()
    ->addParameter($addPetBody);

$operations = [
    $addPet,
];

Responses

A valid Response object requires a status code (or 'default') and a description.

$petResponseModel = (new Schema())
    ->setProperty('id', (new Schema(Type::INTEGER))->setFormat(Format::LONG), true)
    ->setProperty('name', new Schema(Type::STRING), true)
    ->setProperty('tag', new Schema(Type::STRING));

$errorResponseModel = (new Schema())
    ->setProperty('code', (new Schema(Type::INTEGER))->setFormat(Format::INTEGER), true)
    ->setProperty('message', new Schema(Type::STRING), true);

$newPet = (new Schema())
    ->setProperty('id', (new Schema(Type::INTEGER))->setFormat(Format::LONG))
    ->setProperty('name', new Schema(Type::STRING), true)
    ->setProperty('tag', new Schema(Type::STRING));

$addPetBody = (new BodyParameter('pet', true, $newPet))
    ->setDescription('Pet to add to the store');

$responses = [
    (new Response(200, 'pet response'))->setSchema($petResponseModel),
    (new Response('default', 'unexpected error'))->setSchema($errorResponseModel),
];

See /example.php for a complete implementation of all the paths in the Petstore CRUD example.

Swagger JSON

Just json_encode the Swagger object (or any object which extends Component) to get a valid Swagger JSON blob.

echo str_replace(['\/'], ['/'], json_encode($swagger, JSON_PRETTY_PRINT)) . "\n";

Result

{
    "paths": {
        "/pets": {
            "post": {
                "responses": {
                    "200": {
                        "description": "pet response",
                        "schema": {
                            "type": "object",
                            "required": [
                                "id",
                                "name"
                            ],
                            "properties": {
                                "id": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "tag": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "unexpected error",
                        "schema": {
                            "type": "object",
                            "required": [
                                "code",
                                "message"
                            ],
                            "properties": {
                                "code": {
                                    "type": "integer",
                                    "format": "int32"
                                },
                                "message": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                },
                "description": "Creates a new pet in the store. Duplicates are allowed",
                "operationId": "addPet",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "pet",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer",
                                    "format": "int64"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "tag": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "name"
                            ]
                        },
                        "description": "Pet to add to the store"
                    }
                ]
            }
        }
    },
    "swagger": "2.0",
    "info": {
        "title": "Swagger Petstore (Simple)",
        "version": "1.0.0",
        "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification",
        "termsOfService": "http://helloreverb.com/terms/",
        "contact": {
            "name": "Swagger API team",
            "email": "[e-mail]",
            "url": "http://swagger.io"
        },
        "license": {
            "name": "MIT",
            "url": "http://opensource.org/licenses/MIT"
        }
    },
    "host": "petstore.swagger.io",
    "basePath": "/api",
    "schemes": [
        "http"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ]
}