README

这是WakeOnWeb的swagger验证组件的分支。它是一个相当不错的包，但功能相当有限，并且发展非常缓慢 - 它可能是为了满足WakeOnWeb项目的需求而制作的。

我打算在没有上游审批限制的情况下推动这个项目，因为功能性和测试覆盖率存在许多空白。这将适用于v2.x版本。

路线图

* Version 1.0.x (up to 1.0.4) is essentially the same as WakeOnWeb's.
* Version 1.1.x will contain any fixes beyond WakeOnWeb
* Version 2.0.x will go well beyond the original library with OA3 support, framework integrations etc

原始README

WakeOnWeb Swagger验证组件

WakeOnWeb Swagger验证组件是一个可扩展的组件，用于使用Swagger - OpenAPI规范验证API数据。该组件支持YAML和JSON Open API文件格式。组件的依赖性很小，以便可以在不同的PHP框架中使用。

组件使用

• PSR-6：用于缓存OpenApi规范文件
• PSR-7：用于处理HTTP消息（请求和响应）

安装

可以通过以下方式轻松安装组件

composer require wakeonweb/swagger

默认情况下，组件使用JSON Schema验证器，dev依赖项中包含justinrainbow/json-schema。如果您打算在生产中使用组件，则需要执行

composer require justinrainbow/json-schema

加载OpenAPI规范文件

组件支持YAML和JSON OpenAPI格式。Swagger文件由SwaggerFactory加载。工厂接受PSR-6的CacheItemPoolInterface。如果没有提供，它将使用cache/array-adapter提供的ArrayCachePool。

$factory = new SwaggerFactory();

// Register a YAML loader to load YAML Swagger files.
$factory->addLoader(new YamlLoader());

// Load the Swagger definition.
$swagger = $factory->buildFrom('/path/to/swagger/file.yml');

执行此代码将导致将规范的结构表示检索到Swagger文档的实例中。目前，缓存包含Swagger文档的实例。

创建内容验证器

组件中的内容验证基于JSON Schema验证。OpenAPI规范处理的不仅仅是这些。例如，它允许定义查询字符串参数或任何HTTP头的格式。组件支持所有类型的验证。

内容验证器用于验证请求或响应的内容。任何内容验证器都必须实现ContentValidatorInterface，并应将其注册到ContentValidator的实例中。生成的实例可以用于SwaggerValidator的实例。

// Create a content validator that validates requests and responses bodies.
$contentValidator = new ContentValidator();

// Register a specific content validator that handle "application/json".
$contentValidator->registerContentValidator(new JustinRainbowJsonSchemaValidator());

验证响应

验证响应仅在测试中才有意义... 因为在生产环境中，你应该有尊重接口协议的有效代码！

// Create the validator and register the content validator.
$validator = new SwaggerValidator($swagger);
$validator->registerResponseValidator($contentValidator);

// Sample with Symfony Response....
$response = new Response(...);

$psr7Factory = new DiactorosFactory();

// Converts the response to a PRS-7 compliant format.
$response = $psr7Factory->createResponse($response);

try {
    // Validates the response against the required specification.
    $validator->validateResponseFor($response, PathItem::METHOD_GET, '/api/resource', 200);
} catch (SwaggerValidatorException $e) {
    // display $e message.
}

验证请求

验证响应仅在测试中才有意义... 因为在生产环境中，你应该有尊重接口协议的有效代码！

// Create the validator and register the content validator.
$validator = new SwaggerValidator($swagger);
$validator->registerRequestValidator($contentValidator);

// Sample with Symfony Response....
$request = new Request(...);

$psr7Factory = new DiactorosFactory();

// Converts the response to a PRS-7 compliant format.
$request = $psr7Factory->createRequest($request);

try {
    // Validates the request against the required specification.
    $validator->validateRequestFor($request, PathItem::METHOD_GET, '/api/resource');
} catch (SwaggerValidatorException $e) {
    // display $e message.
}

完整示例

以下示例代码演示了组件的完整使用。

<?php

use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory;
use Symfony\Component\HttpFoundation\Response;
use WakeOnWeb\Component\Swagger\Specification\PathItem;
use WakeOnWeb\Component\Swagger\SwaggerFactory;
use WakeOnWeb\Component\Swagger\Loader\YamlLoader;
use WakeOnWeb\Component\Swagger\Loader\JsonLoader;
use WakeOnWeb\Component\Swagger\Test\ContentValidator;
use WakeOnWeb\Component\Swagger\Test\Exception\SwaggerValidatorException;
use WakeOnWeb\Component\Swagger\Test\JustinRainbowJsonSchemaValidator;
use WakeOnWeb\Component\Swagger\Test\SwaggerValidator;

$factory = new SwaggerFactory();

// Register a YAML loader to load YAML Swagger files.
$factory->addLoader(new YamlLoader());

// Load the Swagger definition.
$swagger = $factory->buildFrom('/path/to/swagger/file.yml');

// Create a content validator that validates requests and responses bodies.
$contentValidator = new ContentValidator();

// Register a specific content validator that handle "application/json".
$contentValidator->registerContentValidator(new JustinRainbowJsonSchemaValidator());

// Create the validator and register the content validator.
$validator = new SwaggerValidator($swagger);
$validator->registerResponseValidator($contentValidator);

$response = new Response(
    '{...}',
    200,
    [
        'Content-Type' => 'application/json',
    ]
);

$psr7Factory = new DiactorosFactory();

// Converts the response to a PRS-7 compliant format.
$response = $psr7Factory->createResponse($response);

try {
    // Validates the response against the required specification.
    $validator->validateResponseFor($response, PathItem::METHOD_GET, '/api/resource', 200);
} catch (SwaggerValidatorException $e) {
    // display $e message.
}