README

This library provides a set of classes suited to describe a WebService based on the HTTP protocol.

It can validate PSR-7 Requests against a schema.

It's design is heavily inspired by the OpenAPI/Swagger2.0 specifications.

As of now, it only support the OpenAPi/Swagger2.0 specifications but we plan to support RAML 1.0 and API Elements (API Blueprint) in the future.

Dependencies

We rely on the justinrainbow/json-schema library to parse specification files and to validate requests and responses:

Request's headers, query, uri and body parts.
Response headers and body parts.

Usage

Before you start

You will need to write a valid Swagger 2.0 file in order to use this library. Ensure that this file is valid using the Swagger Editor.

You can also validate your specifications using the Swagger 2.0 JSONSchema.

Validate a request

You can validate any PSR-7:

Request implementing the Psr\Http\Message\RequestInterface interface.
Response implementing the Psr\Http\Message\ResponseInterface interface.

<?php

use JsonSchema\Validator;
use Symfony\Component\Serializer\Encoder\JsonDecode;
use Symfony\Component\Serializer\Encoder\ChainDecoder;
use Symfony\Component\Serializer\Encoder\XmlEncoder;
use TwentytwoLabs\ApiValidator\Factory\SwaggerSchemaFactory;
use TwentytwoLabs\ApiValidator\Factory\OpenApiSchemaFactory;
use TwentytwoLabs\ApiValidator\Decoder\Adapter\SymfonyDecoderAdapter;
use TwentytwoLabs\ApiValidator\Validator\MessageValidator;
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 `TwentytwoLabs\ApiValidator\Decoder\DecoderInterface` 
$decoder = new SymfonyDecoderAdapter(
    new ChainDecoder([
        new JsonDecode(),
        new XmlEncoder()
    ])  
);

// Load a JSON swagger 2.0 schema using the SwaggerSchemaFactory class.
$schema = (new SwaggerSchemaFactory())->createSchema('file://path/to/your/swagger.json');

// Load a JSON swagger 3.0 schema using the OpenApiSchemaFactory class.
$schema = (new OpenApiSchemaFactory())->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);

// ...

Working with Symfony HTTPFoundation Requests

You will need an adapter in order to validate symfony requests.

We recommend you to use the symfony/psr-http-message-bridge

Using the schema

You can navigate the TwentytwoLabs\ApiValidator\Schema to meet other use cases.

Example:

<?php
use TwentytwoLabs\ApiValidator\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->getOperationDefinition(
    $schema->getOperationDefinition(method: 'GET', path: '/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();

twentytwo-labs / api-validator

Maintainers

Details