README

The JsonSchemaValidatorBundle is a Symfony bundle that validate request payload and response with Json Schema for PSR7 & PSR17.

This Bundle is compatible with Symfony >= 5.0

Installation

Install the bundle:

$ composer require nayzo/json-schema-validator-bundle

Usage

Configuration:

# config/packages/nayzo_json_schema_validator.yaml
nayzo_json_schema_validator:
    resources:
        my_account:
            contract_file_path: '%kernel.project_dir%/resources/api_contract/myaccount1.yaml'
            enable_default_request_validation_subscriber: true  # default to false
            enable_default_response_validation_subscriber: true # default to false

        my_second_account:
            contract_file_path: '%kernel.project_dir%/resources/api_contract/myaccount2.yaml'

    enable_default_validation_exception_subscriber: true  # default to false. (if activated, the default validation exception subscriber will be triggered and executed).
    validation_exception_status_code: 400 # default to 422

Define the Validation Support (mandatory):

Note that if no validation support is found (exp: MyAccountValidationSupport), no request/response validation subscriber will be triggered or executed.

<?php

use Nayzo\JsonSchemaValidatorBundle\Configurator\ValidationSubscriberSupportInterface;

final class MyAccountValidationSupport implements ValidationSubscriberSupportInterface
{
    public function __construct(private RequestStack $requestStack)
    {
    }
    
    public function support(): bool
    {
        // some code logic here... example:
        return '/v1/my-account' === $this->requestStack->getMainRequest()->getPathInfo();
    }

    public static function getResourceName(): string
    {
        return 'my_account';  // this value represents the resource name.
    }
}

Use default the request/response validation subscribers:

The JsonSchemaValidatorBundle defines two default validation subscribers: one for requests and another for responses.
These subscribers are responsible for validating request and response schemas.
To activate them, you must enable the corresponding flags: enable_default_request_validation_subscriber and enable_default_response_validation_subscriber, by setting their values to true.

If you prefer to use your own custom validation subscriber instead of the default ones provided by the bundle, you must disable the default subscribers by setting the enable_default_request_validation_subscriber flag to false, and then define the custom validation subscriber you wish to use.

Below is an example of usage without the default request/response validation subscribers.

<?php
    // EventSubscriber
    
    use Nayzo\JsonSchemaValidatorBundle\Validator\ValidatorFactory;
    
    public function __construct(private JsonSchemaValidatorContractInterface $myAccountContract)
    {
    }

    public static function getSubscribedEvents(): array
    {
        return [
            KernelEvents::CONTROLLER => 'onKernelController',
            KernelEvents::RESPONSE => 'onKernelResponse',
        ];
    }
    
    public function onKernelController(ControllerEvent $event): void
    {       
        if ($event->getController() instanceof ErrorController) {
            return;
        }

        $request = $event->getRequest();
        $path = $this->myAccountContract->getContractFile();  // '/some/path/my-contract.yaml'
        
        $validatorFactory = new ValidatorFactory();
        $validator = $validatorFactory->build($path);
        $validator->validate($request, $request->getPathInfo(), $request->getMethod());
    }

    public function onKernelResponse(ResponseEvent $event): void
    {
        $request = $event->getRequest();
        $response = $event->getResponse();
        $path = $this->myAccountContract->getContractFile();  // '/some/path/my-contract.yaml'
        
        $validatorFactory = new ValidatorFactory();
        $validator = $validatorFactory->build($path);
        $validator->validate($response, $request->getPathInfo(), $request->getMethod());
    }

Contract Service Dependency Injection:

<?php

use Nayzo\JsonSchemaValidatorBundle\Contract\JsonSchemaValidatorContractInterface;

    public function __construct(
        private JsonSchemaValidatorContractInterface $myAccountContract, // represent "my_account" in "resources" configuration
        private JsonSchemaValidatorContractInterface $mySecondAccountContract, // represent "my_second_account" in "resources" configuration
    ) {
    }
    
    public function something(): array
    {
        $this->myAccountContract->getContractFile();        // '/some/path/my-contract.yaml'
        $this->mySecondAccountContract->getContractFile();  // '/some/path/my-second-contract.yaml'
    }

// Note: the "Contract" suffix must be added to the contract variable to be loaded correctly.

Exceptions

By default, the value of the enable_default_validation_exception_subscriber flag is set to false. If activated (set to true), the default validation exception subscriber will be triggered and executed.

To use your own custom validation exception subscriber, you must disable the enable_default_validation_exception_subscriber flag by setting its value to false and implement a subscriber that listens to kernel.exception events.

Be aware that when an exception is thrown Before the validation of the request or response implemented by the JsonSchemaValidatorBundle (for example, an access denied), it will be directly intercepted by the application's or framework's kernel.exception and will not be captured by the bundle's validation workflow.

OpenAPI

Official OpenAPI documentation here:

OpenAPI Specification (official): ➡️ https://spec.openapis.org/oas/v3.0.1.html

OpenAPI Guide (Swagger): ➡️ https://swagger.io/specification

Example of openapi implementation:

openapi: 3.0.0
info:
    title: 'Some Title'
    version: 1.0.0
paths:
    /v1/foo:
        get:
            summary: 'Some summary'
            description: 'Some description'
            parameters:
                -   name: uuid
                    in: query
                    required: true
                    schema:
                        type: string

            responses:
                '200':
                    description: 'Some description'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CustomComponent'
                '401':
                    description: Unauthorized
                '403':
                    description: Forbidden
                '404':
                    description: Resource Not Found
                '422':
                    description: Unprocessable Content
                '500':
                    description: Internal server error

        post:
            summary: 'Some summary'
            description: 'Some description'
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - name
                            properties:
                                name:
                                    type: string
                            
            responses:
                '200':
                    description: 'Some description'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CustomComponent'
                '401':
                    description: Unauthorized
                '403':
                    description: Forbidden
                '404':
                    description: Resource Not Found
                '422':
                    description: Unprocessable Content
                '500':
                    description: Internal server error

components:
    schemas:
        CustomComponent:
            type: object
            additionalProperties: false
            required:
                - id
                - name
                - status
            properties:
                id:
                    type: integer
                name:
                    type: string
                status:
                    type: string
                    enum: [enabled, disabled, deleted]

nayzo / json-schema-validator-bundle

Maintainers

Details