Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/codeasashu/openapi-validator
Fork of https://gitlab.com/mmalawski/openapi-validator with some improvements
https://github.com/codeasashu/openapi-validator
Last synced: 9 days ago
JSON representation
Fork of https://gitlab.com/mmalawski/openapi-validator with some improvements
- Host: GitHub
- URL: https://github.com/codeasashu/openapi-validator
- Owner: codeasashu
- License: mit
- Created: 2019-09-21T18:01:32.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-09-21T18:21:34.000Z (over 5 years ago)
- Last Synced: 2024-10-06T00:42:28.482Z (3 months ago)
- Language: PHP
- Size: 332 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## What is this?
Validate data against [openapi v3 spec](https://github.com/OAI/OpenAPI-Specification)
## 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)
8. Supports additionalProperties
Unlike Dredd it does not require examples and does not check that data matches examples
## Installation
```bash
composer req --dev mmal/openapi-validator
```
## Requirements
Your openapi spec has to be valid, You can use [Speccy](https://github.com/wework/speccy) to check Your schema first
This library assumes that each operation has operationId
## Examples
Given we have api described by following OpenAPI specification
```yaml
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
'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
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:
```yaml
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
```
5. Actual response body is validated against that schema
6. 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:
```php
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
```php
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](https://github.com/apiaryio/dredd) - currently supports only swagger/openapi v2, support for v3 is not yet there
2. [Swagger](https://github.com/WakeOnWeb/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