README

此库提供一组类，用于描述基于 HTTP 协议的 Web 服务。

它可以验证针对模式的 PSR-7 请求。

设计灵感主要来自 OpenAPI/Swagger2.0 规范。

目前，它只支持 OpenAPi/Swagger2.0 规范，但我们计划在未来支持 RAML 1.0 和 API Elements (API Blueprint)。

依赖关系

我们依赖于 justinrainbow/json-schema 库来解析规范文件，并验证请求和响应的 headers、query、uri 和 body 部分。

• 请求的 headers、query、uri 和 body 部分。
• 响应的 headers 和 body 部分。

用法

开始之前

您需要编写一个 有效的 Swagger 2.0 文件才能使用此库。请使用 Swagger Editor 确保该文件有效。

您还可以使用 Swagger 2.0 JSONSchema 验证您的规范。

验证请求

您可以验证任何实现 Psr\Http\Message\RequestInterface 接口的 PSR-7

• 请求
• 和实现 Psr\Http\Message\ResponseInterface 接口的响应

<?php

use ElevenLabs\Api\Factory\SwaggerSchemaFactory;
use ElevenLabs\Api\Decoder\Adapter\SymfonyDecoderAdapter;
use ElevenLabs\Api\Validator\MessageValidator;
use JsonSchema\Validator;
use Symfony\Component\Serializer\Encoder\JsonDecode;
use Symfony\Component\Serializer\Encoder\ChainDecoder;
use Symfony\Component\Serializer\Encoder\XmlEncoder;
use GuzzleHttp\Psr7\Request;
use GuzzleHttp\Psr7\Response;

// Given a $request implementing the `Psr\Http\Message\RequestInterface`
// For this example we are using the PSR7 Guzzle implementation;
$request = new Request(
    'POST', 
    'http://domain.tld/api/pets',
    ['application/json'],
    '{"id": 1, "name": "puppy"}'
);

$validator = new Validator();

// Here we are using decoders provided by the symfony serializer component
// feel free to use yours if you so desire. You just need to create an adapter that 
// implement the `ElevenLabs\Api\Decoder\DecoderInterface` 
$decoder = new SymfonyDecoderAdapter(
    new ChainDecoder([
        new JsonDecode(),
        new XmlEncoder()
    ])  
);

// Load a JSON swagger 2.0 schema using the SwaggerSchemaFactory class.
// We plan to support RAML 1.0 and API Elements (API Blueprint) in the future.
$schema = (new SwaggerSchemaFactory())->createSchema('file://path/to/your/swagger.json');

// Find the Request Definition in the Schema API
$requestDefinition = $schema->getRequestDefinition(
  $schema->findOperationId($request->getMethod(), $request->getUri()->getPath())  
);

// Validate the Request
$messageValidator = new MessageValidator($validator, $decoder);
$messageValidator->validateRequest($request, $requestDefinition);

// Check if the request has violations
if ($messageValidator->hasViolations()) {
    // Get violations and do something with them
    $violations = $messageValidator->getViolations();
}

// Using the message Validator, you can also validate a Response
// It will find the proper ResponseDefinition from a RequestDefinition
$response = new Response(
    200, 
    ['Content-Type' => 'application/json'],
    '{"id": 1}'
);

$messageValidator->validateResponse($response, $requestDefinition);

// ...

使用 Symfony HTTPFoundation 请求

您需要一个适配器来验证 symfony 请求。

我们建议您使用 symfony/psr-http-message-bridge

使用模式

您可以使用 ElevenLabs\Api\Schema 导航以满足其他用例。

示例

<?php
use ElevenLabs\Api\Factory\SwaggerSchemaFactory;

$schema = (new SwaggerSchemaFactory())->createSchema('file://path/to/your/swagger.json');

// Find a request definition from an HTTP method and a path.
$requestDefinition = $schema->getRequestDefinition(
    $schema->findOperationId('GET', '/pets/1234')
);

// Get the response definition for the status code 200 (HTTP OK)
$responseDefinition = $requestDefinition->getResponseDefinition(200);

// From here, you can access the JSON Schema describing the expected response
$responseSchema = $responseDefinition->getBodySchema();