README

With the OpenAPI specification generator you're able to create an OpenAPI (or Swagger) specification for your REST API in an object-oriented way.

Installation using Composer

Run the following command to add the package to the composer.json of your project:

$ composer require connectholland/openapi-specification-generator

Usage

It's advisable to read the OpenAPI specification before starting with your own API specification, so you will have a general understanding of the different items within the specification.

All required OpenAPI properties are added as constructor arguments, so you won't accidently forget them and generate an invalid specification.

Basic usage

The following example of the most minimal possible specification you can create.

use ConnectHolland\OpenAPISpecificationGenerator\Info\Info;
use ConnectHolland\OpenAPISpecificationGenerator\Specification;

$info = Info::create('My awesome API', '1.0.0');

$specification = Specification::create($info);

To turn the Specification instance into a JSON specification you can insert the instance into json_encode.

use ConnectHolland\OpenAPISpecificationGenerator\Info\Info;
use ConnectHolland\OpenAPISpecificationGenerator\Specification;

$info = Info::create('My awesome API', '1.0.0');

$specification = Specification::create($info);

echo json_encode($specification, JSON_PRETTY_PRINT);

The above code will generate the following valid API specification in JSON.

{
    "swagger": "2.0",
    "info": {
        "title": "My awesome API",
        "version": "1.0.0"
    },
    "paths": {}
}

Although the above API specification is valid, it's not very useful as it does not contain API endpoints. So, let's try an actual example.

Echo API example

The Echo API example is available within the Swagger editor. The following code shows how to generate this example.

use ConnectHolland\OpenAPISpecificationGenerator\Info\Info;
use ConnectHolland\OpenAPISpecificationGenerator\Parameter\FormDataParameter;
use ConnectHolland\OpenAPISpecificationGenerator\Parameter\PathParameter;
use ConnectHolland\OpenAPISpecificationGenerator\Path\Operation;
use ConnectHolland\OpenAPISpecificationGenerator\Path\PathItem;
use ConnectHolland\OpenAPISpecificationGenerator\Path\Response\Response;
use ConnectHolland\OpenAPISpecificationGenerator\Path\Responses;
use ConnectHolland\OpenAPISpecificationGenerator\Schema\Primitive\StringElement;
use ConnectHolland\OpenAPISpecificationGenerator\Specification;

$info = Info::create('Echo', '1.0.0')
    ->setDescription("#### Echos back every URL, method, parameter and header\nFeel free to make a path or an operation and use **Try Operation** to test it. The echo server will\nrender back everything.\n");

$specification = Specification::create($info)
    ->setHost('mazimi-prod.apigee.net')
    ->setSchemes(array('http'))
    ->setBasePath('/echo');

$specification->setPath('/', PathItem::create()
    ->setGet(
        Operation::create(
            Responses::create()
                ->setResponse(Response::HTTP_OK, Response::create('Echo GET'))
        )
    )
    ->setPost(
        Operation::create(
            Responses::create()
                ->setResponse(Response::HTTP_OK, Response::create('Echo POST'))
        )
        ->addParameter(
            FormDataParameter::create('name', StringElement::create())
                ->setDescription('name')
        )
        ->addParameter(
            FormDataParameter::create('year', StringElement::create())
                ->setDescription('year')
        )
    )
);

$specification->setPath('/test-path/{id}', PathItem::create()
    ->setGet(Operation::create(
            Responses::create()
                ->setResponse(Response::HTTP_OK, Response::create('Echo test-path'))
        )
    )
    ->setParameters(
        array(
            PathParameter::create('id', StringElement::create())->setDescription('ID'),
        )
    )
);

echo json_encode($specification, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

The resulting API specification can be found here.

More examples can be found within the Specification test class.

Credits

This package is written and maintained by Niels Nijens.

Also see the list of contributors who participated in this project.

License

This package is licensed under the MIT License. Please see the LICENSE file for details.

connectholland / openapi-specification-generator

Maintainers

Details