lezhnev74 / openapi-psr7-validator
Validate PSR-7 messages against OpenAPI (3.0.2) specifications expressed in YAML or JSON
Installs: 62 207
Dependents: 1
Suggesters: 0
Security: 0
Stars: 147
Watchers: 14
Forks: 13
Open Issues: 11
Requires
- php: >=7.1
- ext-json: *
- cebe/php-openapi: ^1.2
- psr/cache: ^1.0
- psr/http-message: ^1.0
- psr/http-server-middleware: ^1.0
- respect/validation: ^1.1
- riverline/multipart-parser: ^2.0.3
- webmozart/assert: ^1.4
Requires (Dev)
- cache/array-adapter: ^1.0
- doctrine/coding-standard: ^6.0
- guzzlehttp/psr7: ^1.5
- phpunit/phpunit: ^7|^8
- dev-master
- 0.16
- 0.15.5
- 0.15.4
- 0.15.3
- 0.15.2
- 0.15.1
- 0.15.0
- 0.14.2
- 0.14.1
- 0.14.0
- 0.13.9
- 0.13.8
- 0.13.7
- 0.13.6
- 0.13.5
- 0.13.4
- 0.13.3
- 0.13.2
- 0.13.1
- 0.13.0
- 0.12.0
- 0.11.4
- 0.11.3
- 0.11.2
- 0.11.1
- 0.11.0
- 0.10.3
- 0.10.2
- 0.10.1
- 0.10.0
- 0.9.0
- 0.8.0
- 0.7.0
- 0.6.0
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- dev-62-url-parameters-ints
- dev-44-improve-body-multipart-validation
This package is auto-updated.
Last update: 2019-09-19 17:17:56 UTC
README
NOTICE - THE PACKAGE HAS BEEN CONTRIBUTED TO THE PHP LEAGUE
Go to https://github.com/thephpleague/openapi-psr7-validator
This package is here for existing users only.
OpenAPI PSR-7 Message (HTTP Request/Response) Validator
This package can validate PSR-7 messages against OpenAPI (3.0.x) specifications expressed in YAML or JSON.
Installation
composer require lezhnev74/openapi-psr7-validator
OpenAPI (OAS) Terms
There are some specific terms that are used in the package. These terms come from OpenAPI:
specification
- an OpenAPI document describing an API, expressed in JSON or YAML filedata
- actual thing that we validate against a specification, including body and metadataschema
- the part of the specification that describes the body of the request / responsekeyword
- properties that are used to describe the instance are called key words, or schema keywordspath
- a relative path to an individual endpointoperation
- a method that we apply on the path (likeget /password
)response
- described response (includes status code, content types etc)
How To Validate
ServerRequest Message
You can validate \Psr\Http\Message\ServerRequestInterface
instance like this:
$yamlFile = "api.yaml"; $jsonFile = "api.json"; $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getServerRequestValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYaml(file_get_contents($yamlFile))->getServerRequestValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJson(file_get_contents($jsonFile))->getServerRequestValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJsonFile($jsonFile)->getServerRequestValidator(); #or $schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getServerRequestValidator(); $match = $validator->validate($request);
As a result you would get and OperationAddress $match
which has matched the given request. If you already know
the operation which should match your request (i.e you have routing in your project), you can use
RouterRequestValidator
$address = new \OpenAPIValidation\PSR7\OperationAddress('/some/operation', 'post'); $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getRoutedRequestValidator(); $validator->validate($address, $request);
This would simplify validation a lot and give you more performance.
Request Message
You can validate \Psr\Http\Message\RequestInterface
instance like this:
$yamlFile = "api.yaml"; $jsonFile = "api.json"; $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getRequestValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYaml(file_get_contents($yamlFile))->getRequestValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJson(file_get_contents($jsonFile))->getRequestValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJsonFile($jsonFile)->getRequestValidator(); #or $schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getRequestValidator(); $match = $validator->validate($request);
Response Message
Validation of \Psr\Http\Message\ResponseInterface
is a bit more complicated
. Because you need not only YAML file and Response itself, but also you need
to know which operation this response belongs to (in terms of OpenAPI).
Example:
$yamlFile = "api.yaml"; $jsonFile = "api.json"; $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getResponseValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYaml(file_get_contents($yamlFile))->getResponseValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJson(file_get_contents($jsonFile))->getResponseValidator(); #or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromJsonFile($jsonFile)->getResponseValidator(); #or $schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromSchema($schema)->getResponseValidator(); $operation = new \OpenAPIValidation\PSR7\OperationAddress('/password/gen', 'get') ; $validator->validate($operation, $request);
Reuse Schema After Validation
\OpenAPIValidation\PSR7\ValidatorBuilder
reads and compiles schema in memory as instance of \cebe\openapi\spec\OpenApi
. Validators use this instance to perform validation logic. You can reuse this instance after the validation like this:
$validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getServerRequestValidator(); # or $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder)->fromYamlFile($yamlFile)->getResponseValidator(); /** @var \cebe\openapi\spec\OpenApi */ $openApi = $validator->getSchema();
Request Message
\Psr\Http\Message\RequestInterface
validation is not implemented.
PSR-15 Middleware
PSR-15 middleware can be used like this:
$yamlFile = 'api.yaml'; $jsonFile = 'api.json'; $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYamlFile($yamlFile)->getValidationMiddleware(); #or $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYaml(file_get_contents($yamlFile))->getValidationMiddleware(); #or $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJsonFile($jsonFile)->getValidationMiddleware(); #or $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJson(file_get_contents($jsonFile))->getValidationMiddleware(); #or $schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand $validator = (new \OpenAPIValidation\PSR7\ValidationMiddlewareBuilder)->fromSchema($schema)->getValidationMiddleware();
SlimFramework Middleware
Slim framework uses slightly different middleware interface, so here is an adapter which you can use like this:
$yamlFile = 'api.yaml'; $jsonFile = 'api.json'; $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYamlFile($yamlFile)->getValidationMiddleware(); #or $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromYaml(file_get_contents($yamlFile))->getValidationMiddleware(); #or $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJsonFile($jsonFile)->getValidationMiddleware(); #or $psr15Middleware = (new \OpenAPIValidation\PSR15\ValidationMiddlewareBuilder)->fromJson(file_get_contents($jsonFile))->getValidationMiddleware(); #or $schema = new \cebe\openapi\spec\OpenApi(); // generate schema object by hand $validator = (new \OpenAPIValidation\PSR7\ValidationMiddlewareBuilder)->fromSchema($schema)->getValidationMiddleware(); $slimMiddleware = new \OpenAPIValidation\PSR15\SlimAdapter($psr15Middleware); /** @var \Slim\App $app */ $app->add($slimMiddleware);
Caching Layer / PSR-6 Support
PSR-7 Validator has a built-in caching layer (based on PSR-6 interfaces) which saves time on parsing OpenAPI specs. It is optional. You enable caching if you pass a configured Cache Pool Object to the static constructor like this:
// Configure a PSR-6 Cache Pool $cachePool = new ArrayCachePool(); // Pass it as a 2nd argument $validator = (new \OpenAPIValidation\PSR7\ValidatorBuilder) ->fromYamlFile($yamlFile) ->setCache($cachePool) ->getResponseValidator(); # or \OpenAPIValidation\PSR15\ValidationMiddleware::fromYamlFile($yamlFile, $cachePool);
You can use ->setCache($pool, $ttl)
call for both PSR-7 and PSR-15 builder in order to set
proper expiration ttl in seconds (or explicit null
)
If you want take control over the cache key for schema item, or your cache does not support cache key generation by itself
you can ->overrideCacheKey('my_custom_key')
to ensure cache uses key you want.
Standalone OpenAPI Validator
The package contains a standalone validator which can validate any data against an OpenAPI schema like this:
$spec = <<<SPEC schema: type: string enum: - a - b SPEC; $data = "c"; $spec = cebe\openapi\Reader::readFromYaml($spec); # (optional) reference resolving $spec->resolveReferences(new ReferenceContext($spec, "/")); $schema = new cebe\openapi\spec\Schema($spec->schema); try { (new \OpenAPIValidation\Schema\SchemaValidator())->validate($data, $schema); } catch(\OpenAPIValidation\Schema\Exception\KeywordMismatch $e) { // you can evaluate failure details // $e->keyword() == "enum" // $e->data() == "c" // $e->dataBreadCrumb()->buildChain() -- only for nested data }
Custom Type Formats
As you know, OpenAPI allows you to add formats to types:
schema: type: string format: binary
This package contains a bunch of built-in format validators:
string
type:byte
date
date-time
email
hostname
ipv4
ipv6
uri
uuid
(uuid4)
number
typefloat
double
You can also add your own formats. Like this:
# A format validator must be a callable # It must return bool value (true if format matched the data, false otherwise) # A callable class: $customFormat = new class() { function __invoke($value): bool { return $value === "good value"; } }; # Or just a closure: $customFormat = function ($value): bool { return $value === "good value"; }; # Register your callable like this before validating your data \OpenAPIValidation\Schema\TypeFormats\FormatsContainer::registerFormat('string', 'custom', $customFormat);
Exceptions
The package throws a list of various exceptions which you can catch and handle. There are some of them:
- Schema related:
\OpenAPIValidation\Schema\Exception\KeywordMismatch
- Indicates that data was not matched against a schema's keyword\OpenAPIValidation\Schema\Exception\TypeMismatch
- Validation fortype
keyword failed against a given data. For exampletype:string
and value is12
\OpenAPIValidation\Schema\Exception\FormatMismatch
- data mismatched a given type format. For exampletype: string, format: email
won't matchnot-email
.
- PSR7 Messages related:
\OpenAPIValidation\PSR7\Exception\NoContentType
- HTTP message(request/response) contains no Content-Type header. General HTTP errors.\OpenAPIValidation\PSR7\Exception\NoPath
- path is not found in the spec\OpenAPIValidation\PSR7\Exception\NoOperation
- operation os not found in the path\OpenAPIValidation\PSR7\Exception\NoResponseCode
- response code not found under the operation in the spec- Validation exceptions (check parent exception for possible root causes):
\OpenAPIValidation\PSR7\Exception\ValidationFailed
- generic exception for failed PSR-7 message\OpenAPIValidation\PSR7\Exception\Validation\InvalidBody
- body does not match schema\OpenAPIValidation\PSR7\Exception\Validation\InvalidCookies
- cookies does not match schema or missing required cookie\OpenAPIValidation\PSR7\Exception\Validation\InvalidHeaders
- header does not match schema or missing required header\OpenAPIValidation\PSR7\Exception\Validation\InvalidPath
- path does not match pattern or pattern values does not match schema\OpenAPIValidation\PSR7\Exception\Validation\InvalidQueryArgs
- query args does not match schema or missing required argument\OpenAPIValidation\PSR7\Exception\Validation\InvalidSecurity
- request does not match security schema or invalid security headers
- Request related:
\OpenAPIValidation\PSR7\Exception\MultipleOperationsMismatchForRequest
- request matched multiple operations in the spec, but validation failed for all of them.
Testing
You can run the tests with:
vendor/bin/phpunit
Contribution Guide
Feel free to open an Issue or add a Pull request. There is a certain code style that this package follows: doctrine/coding-standard.
To conform to this style please use a git hook, shipped with this package at .githooks/pre-commit
.
How to use it:
- Clone the package locally and navigate to the folder
- Create a symlink to the hook like this:
ln -s -f ../../.githooks/pre-commit .git/hooks/pre-commit
- Add execution rights:
chmod +x .git/hooks/pre-commit
- Now commit any new changes and the code will be checked and formatted accordingly.
- If there are any issues with your code, check the log here:
.phpcs-report.txt
Credits
People:
- Dmitry Lezhnev
- Carsten Brandt
- Samuel Nela
- Pavel Batanov
- Christopher L Bray
- David Pauli
- Jason Judge
- Yannick Chenot
- TarasBK
- Jason B. Standing
- Dmytro Demchyna
- Will Chambers
- Ignacio
- A big thank you to Henrik Karlström who kind of inspired me to work on this package.
Resources:
- Icons made by Freepik, licensed by CC 3.0 BY
- cebe/php-openapi package for Reading OpenAPI files
- slim3-psr15 package for Slim middleware adapter
License
The MIT License (MIT). Please see License.md
file for more information.
TODO
- Support Discriminator Object (note: apparently, this is not so straightforward, as discriminator can point to any external scheme)