diff --git a/README.md b/README.md index 59e663c..4055153 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,8 @@ Validate HttpFoundation requests and responses against OpenAPI (3.0.x) definitio See [this post](https://tech.osteel.me/posts/openapi-backed-api-testing-in-php-projects-a-laravel-example "OpenAPI-backed API testing in PHP projects – a Laravel example") for more details and [this repository](https://github.com/osteel/openapi-httpfoundation-testing-laravel-example) for an example use in a Laravel project. -💡 _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](../../releases) before you upgrade._ +> **Note** +> 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](../../releases) before you upgrade. ## Why? @@ -25,7 +26,7 @@ This package is built upon the [OpenAPI PSR-7 Message Validator](https://github. It converts HttpFoundation request and response objects to PSR-7 messages using Symfony's [PSR-7 Bridge](https://symfony.com/doc/current/components/psr7.html) and [Tobias Nyholm](https://github.com/Nyholm)'s [PSR-7 implementation](https://github.com/Nyholm/psr7), before passing them on to OpenAPI PSR-7 Message Validator. -## Install +## Installation Via Composer: @@ -33,7 +34,8 @@ Via Composer: $ composer require --dev osteel/openapi-httpfoundation-testing ``` -💡 _This package is mostly intended to be used as part of an API test suite._ +> **Note** +> This package is mostly intended to be used as part of an API test suite. ## Usage @@ -43,17 +45,24 @@ Import the builder class: use Osteel\OpenApi\Testing\ValidatorBuilder; ``` -Use the builder to create a `\Osteel\OpenApi\Testing\Validator` object, feeding it a YAML or JSON OpenAPI definition: +Use the builder to create a `\Osteel\OpenApi\Testing\Validator` object, using one of the available factory methods for YAML or JSON: ```php -$validator = ValidatorBuilder::fromYaml('my-definition.yaml')->getValidator(); +// From a file: -// or +$validator = ValidatorBuilder::fromYamlFile($yamlFile)->getValidator(); +$validator = ValidatorBuilder::fromJsonFile($jsonFile)->getValidator(); -$validator = ValidatorBuilder::fromJson('my-definition.json')->getValidator(); -``` +// From a string: + +$validator = ValidatorBuilder::fromYamlString($yamlString)->getValidator(); +$validator = ValidatorBuilder::fromJsonString($jsonString)->getValidator(); -💡 _Instead of a file, you can also pass a YAML or JSON string directly._ +// Automatic detection (slower): + +$validator = ValidatorBuilder::fromYaml($yamlFileOrString)->getValidator(); +$validator = ValidatorBuilder::fromJson($jsonFileOrString)->getValidator(); +``` You can now validate `\Symfony\Component\HttpFoundation\Request` and `\Symfony\Component\HttpFoundation\Response` objects for a given [path](https://swagger.io/specification/#paths-object) and method: @@ -61,7 +70,8 @@ You can now validate `\Symfony\Component\HttpFoundation\Request` and `\Symfony\C $validator->validate($response, '/users', 'post'); ``` -💡 _For convenience, objects implementing `\Psr\Http\Message\ServerRequestInterface` or `\Psr\Http\Message\ResponseInterface` are also accepted._ +> **Note** +> 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. diff --git a/src/ValidatorBuilder.php b/src/ValidatorBuilder.php index 0a2eef7..8622fad 100644 --- a/src/ValidatorBuilder.php +++ b/src/ValidatorBuilder.php @@ -61,6 +61,50 @@ public static function fromJson(string $definition): ValidatorBuilderInterface return static::fromMethod($method, $definition); } + /** + * {@inheritdoc} + * + * @param string $definition The OpenAPI definition's file. + * @return ValidatorBuilderInterface + */ + public static function fromYamlFile(string $definition): ValidatorBuilderInterface + { + return static::fromMethod('fromYamlFile', $definition); + } + + /** + * {@inheritdoc} + * + * @param string $definition The OpenAPI definition's file. + * @return ValidatorBuilderInterface + */ + public static function fromJsonFile(string $definition): ValidatorBuilderInterface + { + return static::fromMethod('fromJsonFile', $definition); + } + + /** + * {@inheritdoc} + * + * @param string $definition The OpenAPI definition as YAML text. + * @return ValidatorBuilderInterface + */ + public static function fromYamlString(string $definition): ValidatorBuilderInterface + { + return static::fromMethod('fromYaml', $definition); + } + + /** + * {@inheritdoc} + * + * @param string $definition The OpenAPI definition as JSON text. + * @return ValidatorBuilderInterface + */ + public static function fromJsonString(string $definition): ValidatorBuilderInterface + { + return static::fromMethod('fromJson', $definition); + } + /** * Create a Validator object based on an OpenAPI definition. * diff --git a/src/ValidatorBuilderInterface.php b/src/ValidatorBuilderInterface.php index 2998d3f..c078b44 100644 --- a/src/ValidatorBuilderInterface.php +++ b/src/ValidatorBuilderInterface.php @@ -22,6 +22,38 @@ public static function fromYaml(string $definition): ValidatorBuilderInterface; */ public static function fromJson(string $definition): ValidatorBuilderInterface; + /** + * Create a ValidatorBuilderInterface object based on a YAML OpenAPI definition. + * + * @param string $file The OpenAPI definition's file. + * @return ValidatorBuilderInterface + */ + public static function fromYamlFile(string $file): ValidatorBuilderInterface; + + /** + * Create a ValidatorBuilderInterface object based on a JSON OpenAPI definition. + * + * @param string $file The OpenAPI definition's file. + * @return ValidatorBuilderInterface + */ + public static function fromJsonFile(string $file): ValidatorBuilderInterface; + + /** + * Create a ValidatorBuilderInterface object based on a YAML OpenAPI definition. + * + * @param string $definition The OpenAPI definition as YAML text. + * @return ValidatorBuilderInterface + */ + public static function fromYamlString(string $definition): ValidatorBuilderInterface; + + /** + * Create a ValidatorBuilderInterface object based on a JSON OpenAPI definition. + * + * @param string $definition The OpenAPI definition as JSON text. + * @return ValidatorBuilderInterface + */ + public static function fromJsonString(string $definition): ValidatorBuilderInterface; + /** * Return the validator. * diff --git a/tests/ValidatorBuilderTest.php b/tests/ValidatorBuilderTest.php index 2df74e5..92ddb49 100644 --- a/tests/ValidatorBuilderTest.php +++ b/tests/ValidatorBuilderTest.php @@ -17,8 +17,12 @@ public function definitionProvider(): array return [ ['fromYaml', self::$yamlDefinition], ['fromYaml', file_get_contents(self::$yamlDefinition)], + ['fromYamlFile', self::$yamlDefinition], + ['fromYamlString', file_get_contents(self::$yamlDefinition)], ['fromJson', self::$jsonDefinition], ['fromJson', file_get_contents(self::$jsonDefinition)], + ['fromJsonFile', self::$jsonDefinition], + ['fromJsonString', file_get_contents(self::$jsonDefinition)], ]; }