README

PSR-7 and PSR-15 OpenAPI Validation Middleware

The middleware parses an OpenAPI definition document (openapi.json or openapi.yaml) and validates:

Request parameters (path, query)
Request body
Response body

The middleware can be used with any framework using PSR-7 and PSR-15 style middlewares.

All testing has been done using Slim Framework. The tests are done with a openapi.json file that is valid according to Swagger/OpenAPI CLI

Installation

It's recommended that you use Composer to install.

composer require hkarlstrom/openapi-validation-middleware

Use Swagger/OpenAPI CLI to validate openapi.json/openapi.yaml file, as the middleware assumes it to be valid.

Usage

Basic usage with Slim Framework.

$config = [
    'settings' => [
        'determineRouteBeforeAppMiddleware' => true,
    ],
];
$app = new \Slim\App($config);
$app->add(new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json'));

Basic usage with Zend Expressive.

$app = $container->get(\Zend\Expressive\Application::class);
$app->pipe(new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json'));

Options

The options array is passed to the middleware when it's constructed.

$app = new Slim\App;
$app->add(new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json'),[
    'additionalParameters' => true,
    'stripResponse' => true
]);

type	format	default	description
additionalParameters	bool	false	Allow additional parameters in query
beforeHandler	callable	null	Instructions below
errorHandler	callable	null	Instructions below
exampleResponse	bool	false	Return example response from openapi.json/openapi.yaml if route implementation is empty
missingFormatException	bool	true	Throw an exception if a format validator is missing
pathNotFoundException	bool	true	Throw an exception if the path is not found in openapi.json/openapi.yaml
setDefaultParameters	bool	false	Set the default parameter values for missing parameters and alter the request object
strictEmptyArrayValidation	bool	false	Consider empty array when object is expected as validation error
stripResponse	bool	false	Strip additional attributes from response to prevent response validation error
stripResponseHeaders	bool	false	Strip additional headers from response to prevent response validation error
validateError	bool	false	Should the error response be validated
validateRequest	bool	true	Should the request be validated
validateResponse	bool	true	Should the response's body be validated
validateResponseHeaders	bool	false	Should the response's headers be validated
validateSecurity	callable	null	Instructions below

beforeHandler

If defined, the function is called when the request validation fails before the next incoming middleware is called. You can use this to alter the request before passing it to the next incoming middleware in the stack. If it returns anything else than \Psr\Http\Message\ServerRequestInterface an exception will be thrown. The array $errors is an array containing all the validation errors.

$options = [
    'beforeHandler' => function (\Psr\Http\Message\ServerRequestInterface $request, array $errors) : \Psr\Http\Message\ServerRequestInterface {
        // Alter request
        return $request
    }
];

errorHandler

If defined, the function is called instead of the default error handler. If it returns anything else than Psr\Http\Message\ResponseInterface it will fallback to the default error handler.

$options = [
    'errorHandler' => function (int $code, string $message, array $errors) : \Psr\Http\Message\ResponseInterface {
        // Alter request
        return $request
    }
];

validateSecurity

If defined, the callback can return Psr\Http\Message\ResponseInterface if the operation is not allowed. $type can be none, http or apiKey.

$options = [
    'validateSecurity' => function (ServerRequestInterface $request, string $type, string $token = '', ?array $scopes) : ?\Psr\Http\Message\ResponseInterface {
        // if user is authorized
        return null;

        // create and return error response
        $response = new Response( ... );
        return $response;
    }
];

Formats

There are two ways to validate formats not defined in the OAS specification. You can implement a custom format validator and add it to the middleware, or use the build in support for the Respect Validation libray.

Custom validator

class MyOwnFormat implements Opis\JsonSchema\Format {
    public function validate($data) : bool
    {
        // Validate data
        // $isValid = ...
        return $isValid;
    }
}

$mw = new HKarlstrom\Middleware\OpenApiValidation('/path/to/openapi.json');
$mw->addFormat('string','my-own-format',new MyOwnFormat());
$app->add($mw);

Respect Validation

You can use all the validators just by setting the format property in your openapi.json/openapi.yaml file.

"schema":{
    "type" : "string",
    "format": "country-code"
}

The country-code value will resolve to the v::countryCode() validator.

You can also pass arguments to the validator defined in the format attribute:

"schema": {
    "type": "string",
    "format":"ends-with('@gmail.com')"
}

"schema": {
    "type": "integer",
    "format":"between(10, 20)"
}

License

The OpenAPI Validation Middleware is licensed under the MIT license. See License File for more information.

hkarlstrom / openapi-validation-middleware

Maintainers

Details