mmal/openapi-validator

Validates data against provide openapi spec

0.9.12 2020-10-12 10:19 UTC

Requires

• php: >=7.0
• justinrainbow/json-schema: ^5.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.13
• phpunit/phpunit: ^6.5
• symfony/yaml: ^3.4

proprietary

• swagger
• openapi

README

This project is abandoned. Reasons: 1. there are more mature and better developed libraries similar to this one 2. I don't have time anymore to maintain this. If You believe that this project should be still expanded then feel free to fork.

What is this?

Validate data against openapi v3 spec

Features

1. Checks for required fields
2. Checks types
3. Supports nested structures
4. Supports discriminator
5. Supports allOf, anyOf
6. Supports nullable
7. Resolves local references (components)

Unlike Dredd it does not require examples and does not check that data matches examples

Installation

composer req --dev mmal/openapi-validator

Requirements

Your openapi spec has to be valid, You can use Speccy to check Your schema first

This library assumes that each operation has operationId

Examples

Given we have api described by following OpenAPI specification

openapi: 3.0.2
info:
  title: Cards
  description: Cards and decks api
  contact:
    name: Mieszko Malawski
  license:
    name: GNU AGPLv3
    url: https://www.gnu.org/licenses/agpl.txt
  version: 1.0.0
tags:
  -
    name: Cards
paths:
  /cards:
    summary: Path used to manage the list of cards.
    description: The REST endpoint/path used to list and create zero or more card entities.  This path contains a GET and POST operation to perform the list and create tasks, respectively.
    get:
      tags:
        - Cards
      summary: List All cards
      description: Gets a list of all card entities.
      operationId: getcards
      responses:
        200:
          description: Successful response - returns an array of card entities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/card'
components:
  schemas:
    card:
      title: Root Type for card
      description: The root of the card type's schema.
      required:
      - id
      - name
      - power
      type: object
      properties:
        id:
          description: "unique id"
          type: string
          format: int64
          readOnly: true
        name:
          type: string
        power:
          description: "how powerfull card is on the board"
          format: int32
          type: integer
      example:
        id: "23423423"
        name: "Geralt"
        power: 10
        

We have server implementation (this is of course example - normally You would fetch data from some storage)

<?php
declare(strict_types=1);


namespace AppBundle\Controller;


use GOG\Common\OAuthSecurityBundle\Controller\OAuthController;
use Symfony\Component\HttpFoundation\JsonResponse;

class CardsController extends OAuthController
{
    public function getCardsAction()
    {
        return new JsonResponse(
            [
                [
                    'id' => '123123',
                    'name' => 'Geralt',
                    'power' => 10,
                ],
                [
                    'id' => '45653',
                    'name' => 'Vernon Roche',
                    'power' => 10,
                ]
            ]
        );
    }
}

How to verify that server implementation works as described? Use openapi-validator with any http client:

<?php
declare(strict_types=1);


namespace AppBundle\Tests\Controller;


use Mmal\OpenapiValidator\Validator;
use Symfony\Component\Yaml\Yaml;

class CardsControllerTest extends BaseControllerTest
{
    const SPEC_PATH = __DIR__.'/../../../../docs/api.yml';
    
    /** @var Validator */
    static $openaApiValidator;

    static public function setUpBeforeClass()
    {
        parent::setUpBeforeClass();
        self::$openaApiValidator = new Validator(Yaml::parse(self::SPEC_PATH));
    }

    public function testGetCards()
    {
        $this->makeRequest('GET', '/cards');
    }

    protected function makeRequest($method, $uri, $content = '')
    {
        $client = $this->getTestClient();
        $client->request(
            $method,
            $uri
        );
        $response = $client->getResponse();

        $result = self::$openaApiValidator->validateBasedOnRequest(
            $uri,
            $method,
            $response->getStatusCode(),
            json_decode($response->getContent(), true)
        );
        self::assertFalse($result->hasErrors(), $result);

        return RESTResponse::fromHTTPResponse($response);
    }
}

1. Load Your spec to validator
2. Make request with any http client
3. Pass request uri, request method, response code and response body to validator (and optionally media type, default is application/json)
4. Validator will find figure out that for method 'GET', path '/cards' and response code 200, required response schema is:

card:
  title: Root Type for card
  description: The root of the card type's schema.
  required:
  - id
  - name
  - power
  type: object
  properties:
	id:
	  description: "unique id"
	  type: string
	  format: int64
	  readOnly: true
	name:
	  type: string
	power:
	  description: "how powerfull card is on the board"
	  format: int32
	  type: integer
  example:
	id: "23423423"
	name: "Geralt"
	power: 10

1. Actual response body is validated against that schema
2. Result object is produced, if response is invalid then result object will contain errors

In this case response is valid:

Lets now introduce some errors:

 public function getCardsAction()
    {
        return new JsonResponse(
            [
                [
                    'id' => '123123',
                    'name' => 'Geralt',
                    'power' => 10,
                ],
                [
                 //   'id' => '45653',
                    'name' => 'Vernon Roche',
                    'power' => 10,
                ]
            ]
        );
    }
    

Required id field for second item is missing:

Lets break something else

public function getCardsAction()
    {
        return new JsonResponse(
            [
                [
                    'id' => '123123',
                    'name' => 'Geralt',
                    'power' => 10,
                ],
                [
                    'id' => '45653',
                    'name' => 'Vernon Roche',
                    'power' => '10',
                ]
            ]
        );
    }
    

power field should be integer (second item):

Other libraries

1. Dredd - currently supports only swagger/openapi v2, support for v3 is not yet there
2. Swagger - support for v2 only

TODO

1. Support all openapi formats
2. Support for not keyword

How this works?

Transform openapi spec into json schema and then uses justinrainbow/json-schema to validate it