codeasashu / openapi-validator
Validates data against provide openapi spec
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
README
Validate data against openapi v3 spec
Features
- Checks for required fields
- Checks types
- Supports nested structures
- Supports discriminator
- Supports allOf, anyOf
- Supports nullable
- Resolves local references (components)
- Supports additionalProperties
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); } }
- Load Your spec to validator
- Make request with any http client
- Pass request uri, request method, response code and response body to validator (and optionally media type, default is application/json)
- 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
- Actual response body is validated against that schema
- 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
- Dredd - currently supports only swagger/openapi v2, support for v3 is not yet there
- Swagger - support for v2 only
TODO
- Support all openapi formats
- Support for not keyword
How this works?
Transform openapi spec into json schema and then uses justinrainbow/json-schema to validate it