jessedc / php-openapi

READ OpenAPI yaml files and make the content accessable in PHP objects.

php-openapi

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

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:

• https://github.com/cebe/yii2-openapi
• ... (add yours)

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
    • Runtime Expressions
  • 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.:cloud: "Your Professional Deployment Platform".