How to Quickly Implement an API using a PHP OpenAPI Parser that Can Generate Routes to Forward Requests to Command Handler Classes - PHP OpenAPI Dispatcher package blog

In this article you will learn:

The Power of Describing an API Using OpenAPI

Maybe it's about automation, or just about being more declarative because a Domain Specific Language (DSL) non-Touring complete language will just be more correct.

Anyway I find it amazing the possibility to describe an API by using the OpenAPI Specification and let this specification be your code.

Turning an API Specification using OpenAPI into a Real API

Using an API specification using the OpenAPI format is just the start of your work when you create an API. After doing that, you need to implement how the API functions will respond to the API requests. The PHP OpenAPI Dispatcher package can help you doing that.

This package will setup every route that is necessary to configure how requests are dispatched to CommandHandler classes that you should write to handle the API requests and generate the respective responses.

Check a Real Example of an API Implemented with the PHP OpenAPI Dispatcher

The best way I can suggest for you to see this package in action is just to clone the Git repository and try the Example Hello World Application. You can do that by running the following commands from your command line interface (shell).

git clone git@github.com/virgiliolino/open-api.git
cd open-api/Examples/HelloWorld/

#composer install will actually install this package
composer install

#start the server
php -S localhost:8080 -t public public/index.php

# Retrieve the API response using curl
# just open the browser localhost:8080/hello/world
curl localhost:8080/hello/world

Using the approach proposed by the use of this package you doe not need to add many functions to your controller classes.

Instead, you just need to create one command handler class for every API function that you want to implement.

You can read at this blog post to learn more about how to implement this approach of handling different API functions using request handlers instead of controllers functions.

In the end you just need have a YML or JSON configuration file that describes your API that looks like this:

By using the PHP OpenAPI Dispatcher package, all routes will automatically be set. Every route points to a CommandHandler that is set in the OpenID description using a unique operationId.

So in the image of the example above, you can see that there is a route: /pet that accept post requests. This setting is enough to configure our class.

When you start the API application, the route /pet will be prepared to accept a POST request.

For the GET requests that you may see below, there are API functions like /pet/findByStatus among others.

For every API function that is called, it will be executed the command handler with the operation.

In the example for /pet, you can see the operationId: addPet. So sending a POST request to /pet, the system will try to execute the class AddPet::execute passing the params.

The operationId must be a fully qualified name of the respective command handler class. It can be something like this for example: operationId: \MyApplication\CommandHandlers\AddPett which means that will execute AddPett::execute .

You may find an example of a fully working OpenAPI specification here, as well the the full json file.

How to Install the PHP OpenAPI Dispatcher Package

Even if its working, I'd not consider it really a stable package. So to install it you need to proceed in that way:

 composer require dispatcher/openapi dev-master

You can also install the package from the PHP Classes site using composer following instructions in this page.

If you prefer, you can also download and install the package manually by going to the package download page.

How to Use the PHP OpenAPI Dispatcher Package

$app = new \Slim\App;
$container = $app->getContainer();
$container['HelloWorld'] = function () {
    return new \HelloWorld\CommandHandlers\HelloWorld();
};
$openApiFile = 'routes.json';
$openApiConfigParser = Dispatcher\OpenApi\ParserFactory::parserFor( $openApiFile );
$openApiConfig = $openApiConfigParser->parse( $openApiFile );
\Dispatcher\OpenApi\OpenApiDispatcher::InjectRoutesFromConfig($app, $openApiConfig);
$app->run();

There is no validation at all. This process can be automatized.

If you liked this article and this package, you can view more details in the package page.