Awesome
OpenAPI HttpFoundation Testing
Validate HttpFoundation requests and responses against OpenAPI (3+) definitions.
See this post for more details and this repository for an example use in a Laravel project.
[!IMPORTANT] While you can safely use this package for your projects, as long as version
1.0
has not been released "minor" version patches can contain breaking changes. Make sure to check the release section before you upgrade.
Why?
OpenAPI is a specification intended to describe RESTful APIs in a way that can be understood by both humans and machines.
By validating an API's requests and responses against the OpenAPI definition that describes it, we guarantee that the API is used correctly and behaves in accordance with the documentation we provide, thus making the OpenAPI definition the single source of truth.
The HttpFoundation component is developed and maintained as part of the Symfony framework. It is used to handle HTTP requests and responses in projects such as Symfony, Laravel, Drupal, and many others.
How does it work?
This package is built on top of OpenAPI PSR-7 Message Validator, which validates PSR-7 messages against OpenAPI definitions.
It converts HttpFoundation request and response objects to PSR-7 messages using Symfony's PSR-7 Bridge and Tobias Nyholm's PSR-7 implementation, before passing them on to OpenAPI PSR-7 Message Validator.
Installation
[!NOTE] This package is mostly intended to be used as part of an API test suite.
Via Composer:
composer require --dev osteel/openapi-httpfoundation-testing
Usage
Import the builder class:
use Osteel\OpenApi\Testing\ValidatorBuilder;
Use the builder to create a \Osteel\OpenApi\Testing\Validator
object, using one of the available factory methods for YAML or JSON:
// From a file:
$validator = ValidatorBuilder::fromYamlFile($yamlFile)->getValidator();
$validator = ValidatorBuilder::fromJsonFile($jsonFile)->getValidator();
// From a string:
$validator = ValidatorBuilder::fromYamlString($yamlString)->getValidator();
$validator = ValidatorBuilder::fromJsonString($jsonString)->getValidator();
// Automatic detection (slower):
$validator = ValidatorBuilder::fromYaml($yamlFileOrString)->getValidator();
$validator = ValidatorBuilder::fromJson($jsonFileOrString)->getValidator();
[!TIP] You can also use a dependency injection container to bind the
ValidatorBuilder
class to theValidatorBuilderInterface
interface it implements and inject the interface instead, which would also be useful for testing and mocking.
You can now validate \Symfony\Component\HttpFoundation\Request
and \Symfony\Component\HttpFoundation\Response
objects for a given path and method:
$validator->validate($response, '/users', 'post');
[!TIP] For convenience, objects implementing
\Psr\Http\Message\ServerRequestInterface
or\Psr\Http\Message\ResponseInterface
are also accepted.
In the example above, we check that the response matches the OpenAPI definition for a POST
request on the /users
path.
Each of OpenAPI's supported HTTP methods (DELETE
, GET
, HEAD
, OPTIONS
, PATCH
, POST
, PUT
and TRACE
) also has a shortcut method that calls validate
under the hood, meaning the line above could also be written this way:
$validator->post($response, '/users');
Validating a request object works exactly the same way:
$validator->post($request, '/users');
In the example above, we check that the request matches the OpenAPI definition for a POST
request on the /users
path.
The validate
method returns true
in case of success, and throw a \Osteel\OpenApi\Testing\Exceptions\ValidationException
exception in case of error.
Caching
This package supports caching to speed up the parsing of OpenAPI definitions. Simply pass your PSR-6 or PSR-16 cache object to the setCache
method of the ValidatorBuilder
class.
Here is an example using Symfony's Array Cache Adapter:
use Osteel\OpenApi\Testing\ValidatorBuilder;
use Symfony\Component\Cache\Adapter\ArrayAdapter;
$cache = new ArrayAdapter();
$validator = ValidatorBuilder::fromYamlFile($yamlFile)->setCache($cache)->getValidator();
Extending the package
There are two main extension points – message adapters and cache adapters.
Message adapters
The ValidatorBuilder
class uses the HttpFoundationAdapter
class as its default HTTP message adapter. This class converts HttpFoundation request and response objects to their PSR-7 counterparts.
If you need to change the adapter's logic, or if you need a new adapter altogether, create a class implementing the MessageAdapterInterface
interface and pass it to the setMessageAdapter
method of the ValidatorBuilder
class:
$validator = ValidatorBuilder::fromYamlFile($yamlFile)
->setMessageAdapter($yourAdapter)
->getValidator();
Cache adapters
The ValidatorBuilder
class uses the Psr16Adapter
class as its default cache adapter. This class converts PSR-16 cache objects to their PSR-6 counterparts.
If you need to change the adapter's logic, or if you need a new adapter altogether, create a class implementing the CacheAdapterInterface
interface and pass it to the setCacheAdapter
method of the ValidatorBuilder
class:
$validator = ValidatorBuilder::fromYamlFile($yamlFile)
->setCacheAdapter($yourAdapter)
->getValidator();
Other interfaces
The ValidatorBuilder
and Validator
classes are final
but they implement the ValidatorBuilderInterface
and ValidatorInterface
interfaces respectively for which you can provide your own implementations if you need to.
Change log
Please see the Releases section for details.
Contributing
Please see CONTRIBUTING for details.
Credits
People
Special thanks to Pavel Batanov for his advice on structuring the package.
Packages
License
The MIT License (MIT). Please see License File for more information.