README

验证 HttpFoundation 请求和响应是否与 OpenAPI (3+) 定义一致。

详见这篇博客获取更多详细信息，以及此存储库中在 Laravel 项目中使用的示例。

💡 尽管您可以安全地在项目中使用此包，但在 1.0 版本发布之前，“次要”版本补丁可能包含破坏性更改。在升级之前，请务必检查版本发布部分。

为什么？

OpenAPI 是一种旨在以人类和机器都能理解的方式描述 RESTful API 的规范。

通过将 API 的请求和响应与描述它的 OpenAPI 定义进行验证，我们保证 API 正确使用，并按我们提供的文档行为，从而使 OpenAPI 定义成为唯一的真相来源。

HttpFoundation 组件是作为 Symfony 框架的一部分开发和维护的。它用于处理诸如 Symfony、Laravel、Drupal 和许多其他项目的 HTTP 请求和响应。

它是如何工作的？

此包建立在 OpenAPI PSR-7 Message Validator 之上，该工具验证 PSR-7 消息是否与 OpenAPI 定义一致。

它使用 Symfony 的 PSR-7 Bridge 和 Tobias Nyholm 的 PSR-7 实现将 HttpFoundation 请求和响应对象转换为 PSR-7 消息，然后再将它们传递给 OpenAPI PSR-7 Message Validator。

安装

💡 此包主要设计用于作为 API 测试套件的一部分使用。

通过 Composer

$ composer require --dev osteel/openapi-httpfoundation-testing

使用方法

导入构建器类

use Osteel\OpenApi\Testing\ValidatorBuilder;

使用构建器创建一个 \Osteel\OpenApi\Testing\Validator 对象，使用可用的 YAML 或 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();

💡 您还可以使用依赖注入容器将 ValidatorBuilder 类绑定到它实现的 ValidatorBuilderInterface 接口，并注入接口，这对于测试和模拟也很有用。

现在您可以为给定的路径和方法验证 \Symfony\Component\HttpFoundation\Request 和 \Symfony\Component\HttpFoundation\Response 对象。

$validator->validate($response, '/users', 'post');

💡 为了方便，实现 \Psr\Http\Message\ServerRequestInterface 或 \Psr\Http\Message\ResponseInterface 的对象也被接受。

在上面的示例中，我们检查响应是否符合 /users 路径上 POST 请求的 OpenAPI 定义。

OpenAPI 所支持的每个 HTTP 方法（DELETE、GET、HEAD、OPTIONS、PATCH、POST、PUT 和 TRACE）都有一个快捷方法，在内部调用 validate，这意味着上面的行也可以这样写

$validator->post($response, '/users');

验证请求对象的工作方式完全相同

$validator->post($request, '/users');

在上面的示例中，我们检查请求是否符合 /users 路径上 POST 请求的 OpenAPI 定义。

validate 方法在成功时返回 true，在出错时抛出 \Osteel\OpenApi\Testing\Exceptions\ValidationException 异常。

缓存

此包支持缓存以提高 OpenAPI 定义的解析速度。只需将您的 PSR-6 或 PSR-16 缓存对象传递给 ValidatorBuilder 类的 setCache 方法。

下面是一个使用 Symfony 的 Array Cache Adapter 的示例

use Osteel\OpenApi\Testing\ValidatorBuilder;
use Symfony\Component\Cache\Adapter\ArrayAdapter;

$cache = new ArrayAdapter();
$validator = ValidatorBuilder::fromYamlFile($yamlFile)->setCache($cache)->getValidator();

扩展包

有两个主要的扩展点 - 消息适配器和缓存适配器。

消息适配器

ValidatorBuilder 类使用 HttpFoundationAdapter 类作为其默认的 HTTP 消息适配器。此类将 HttpFoundation 请求和响应对象转换为 PSR-7 对应物。

如果您需要更改适配器的逻辑，或者如果您需要全新的适配器，请创建一个实现 MessageAdapterInterface 接口的类，并将其传递给 ValidatorBuilder 类的 setMessageAdapter 方法。

$validator = ValidatorBuilder::fromYamlFile($yamlFile)
    ->setMessageAdapter($yourAdapter)
    ->getValidator();

缓存适配器

ValidatorBuilder 类使用 Psr16Adapter 类作为其默认的缓存适配器。此类将 PSR-16 缓存对象转换为 PSR-6 对应物。

如果您需要更改适配器的逻辑，或者如果您需要全新的适配器，请创建一个实现 CacheAdapterInterface 接口的类，并将其传递给 ValidatorBuilder 类的 setCacheAdapter 方法。

$validator = ValidatorBuilder::fromYamlFile($yamlFile)
    ->setCacheAdapter($yourAdapter)
    ->getValidator();

其他接口

ValidatorBuilder 和 Validator 类是 final 的，但它们分别实现了 ValidatorBuilderInterface 和 ValidatorInterface 接口，您可以根据需要提供自己的实现。

变更日志

请参阅版本发布部分以获取详细信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

致谢

人物

特别感谢Pavel Batanov在包结构方面的建议。

包

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

osteel / openapi-httpfoundation-testing

维护者

详细信息