READ OpenAPI yaml files and make the content accessable in PHP objects.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc ArrayAccess and Interator for Paths and ResponseArrayAccess and Nov 16, 2018
src fix code style Nov 28, 2018
tests cleanup Nov 22, 2018
.gitignore add php-cs-fixer Nov 7, 2018
.php_cs.dist cleanup author tags Nov 7, 2018
.travis.yml php-cs-fixer does not work on PHP >7.2 Nov 16, 2018
LICENSE
Makefile
README.md
composer.json OpenAPI test Nov 16, 2018
phpunit.xml.dist initial implementation Oct 23, 2018

README.md

php-openapi

READ OpenAPI 3.0.x YAML and JSON files and make the content accessible in PHP objects.

Latest Stable Version Build Status License

Install

composer require cebe/php-openapi:~0.9@beta

Requirements

  • PHP 7.1 or higher

Used by

This library provides a low level API for reading OpenAPI files. It is used by higher level tools to do awesome work:

Usage

Reading Specification information

Read OpenAPI spec from JSON:

use cebe\openapi\Reader;

$openapi = Reader::readFromJson(file_get_contents('openapi.json'));

Read OpenAPI spec from YAML:

use cebe\openapi\Reader;

$openapi = Reader::readFromYaml(file_get_contents('openapi.yaml'));

Access specification data:

echo $openapi->openapi; // openAPI version, e.g. 3.0.0
echo $openapi->info->title; // API title
foreach($openapi->paths as $path => $definition) {
    // iterate path definitions
}

Object properties are exactly like in the OpenAPI specification. You may also access additional properties added by specification extensions.

Reading Specification Files and Resolving References

In the above we have passed the raw JSON or YAML data to the Reader. In order to be able to resolve references to external files that may exist in the specification files, we must provide the full context.

use cebe\openapi\Reader;
// an absolute URL or file path is needed to allow resolving internal references
$openapi = Reader::readFromJsonFile('https://www.example.com/api/openapi.json');
$openapi = Reader::readFromYamlFile('https://www.example.com/api/openapi.yaml');

If data has been loaded in a different way you can manually resolve references like this by giving a context:

$openapi->resolveReferences(
    new \cebe\openapi\ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml')
);

Note: Resolving references currently does not deal with references in referenced files, you have to call it multiple times to resolve these.

Validation

The library provides simple validation operations, that check basic OpenAPI spec requirements.

// return `true` in case no errors have been found, `false` in case of errors.
$specValid = $openapi->validate();
// after validation getErrors() can be used to retrieve the list of errors found.
$errors = $openapi->getErrors();

Note: Validation is done on a very basic level and is not complete. So a failing validation will show some errors, but the list of errors given may not be complete. Also a passing validation does not necessarily indicate a completely valid spec.

Completeness

This library is currently work in progress, the following list tracks completeness:

  • read OpenAPI 3.0 JSON
  • read OpenAPI 3.0 YAML
  • OpenAPI 3.0 Schema
    • OpenAPI Object
    • Info Object
    • Contact Object
    • License Object
    • Server Object
    • Server Variable Object
    • Components Object
    • Paths Object
    • Path Item Object
    • Operation Object
    • External Documentation Object
    • Parameter Object
    • Request Body Object
    • Media Type Object
    • Encoding Object
    • Responses Object
    • Response Object
    • Callback Object
    • Example Object
    • Link Object
    • Header Object
    • Tag Object
    • Reference Object
    • Schema Object
      • load/read
      • validation
    • Discriminator Object
    • XML Object
    • Security Scheme Object
    • OAuth Flows Object
    • OAuth Flow Object
    • Security Requirement Object

Support

Professional support, consulting as well as software development services are available:

https://www.cebe.cc/en/contact

Development of this library is sponsored by cebe.☁️ "Your Professional Deployment Platform".