README

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

组件使用

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

安装

可以使用以下方法轻松安装组件

composer require wakeonweb/swagger

组件使用 JSON Schema 验证器，默认情况下，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 PSR-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.
}