avalanche-development/swagger-router-middleware

swagger-router-middleware

PHP middleware that parses and attaches swagger information to a request object., _(*1)

, _(*2)

Installation

It's recommended that you use Composer to install swagger-router-middleware., _(*3)

$ composer require avalanche-development/swagger-router-middleware

swagger-router-middleware requires PHP 5.6 or newer., _(*4)

Usage

This middleware is instantiated with swagger (in the form of an array) and then, when invoked as middleware, will walk through the swagger document and parse things out. Specifically, it will pull out the path and operation, resolve parameters and security definitions, and parse out parameters based on the swagger definition., _(*5)

$router = new AvalancheDevelopment\SwaggerRouterMiddleware\Router([..swagger..]);
$result = $router($request, $response, $next); // middleware signature

It is recommended that this is one of the top items in the stack, as the swagger information that is parsed out can be used for request/response validation deeper in., _(*6)

Interface

Once everything passes through successfully, the $request object will have the following attribute passed on., _(*7)

'swagger' => [
    'apiPath' => '/comments/{comment_id}', // matched string path
    'path' => [ ... ], // full path definition
    'operation' => [ ... ], // specific operation definition
    'params' => [ ... ], // resolved list of parameters for this operation
    'security' => [ ... ], // resolved list of securities
    'schemes' => [ ... ], // resolved list of schemes
    'produces' => [ ... ], // resolved list of producible content types
    'consumes' => [ ... ], // resolved list of consumable content types
    'responses' => [ ... ], // resolved list of responses
]

An important note is that each parameter in the list will include a 'value' key that, if the parameter was passed into the request (or has a default), will be populated., _(*8)

Documentation Route

If the standard 'documentation route' is detected (path of /api-docs), the rest of the stack is immediately skipped and the swagger spec is returned as json. An error with json_encode will throw a standard \Exception., _(*9)

Invalid Requests

There is some routing being done here. If the request route cannot be found in swagger, or if the method is not supported, appropriate peel exceptions are thrown. Also, if there is an error with parameter parsing that appears to be an issue with request, a peel BadRequest is thrown. An error handler can listen for these HttpErrorInterface exceptions and respond appropriately., _(*10)

Parameter Parsing

The middleware will do it's best to parse out the parameters for the request without too much validation. It loops through the swagger definition, looking for the parameters that are applicable for the route, and pull them from header/query/path/etc., _(*11)

Again, this middleware will not check the existence, validity, or type of parameters based on the spec. It only tries to pull and expects something else in the stack to verify integrity., _(*12)

Development

This library is still being developed and some bugs may be experienced. Feel free to add issues or submit pull requests when road bumps are noticed., _(*13)

Tests

To execute the test suite, you'll need phpunit (and to install package with dev dependencies)., _(*14)

$ phpunit

License

swagger-router-middleware is licensed under the MIT license. See License File for more information., _(*15)