README

OpenAPI Specification parser for PHP 8. Supports both OAS 3.0 and 3.1.

Features

• Parse OpenAPI files into a PHP object to interact with in code
• Validate OpenAPI files against the official JSON-schema descriptions
• Resolve external and internal references

Installation

composer require apiboard/php-openapi

Usage

You can interact with this library through the OpenAPI::class directly.

$openAPI = new OpenAPI();

This class optionally accepts an implementation of Apiboard\OpenAPI\Contents\Retriever::class which will be used to retrieve the file contents. By default the local filesystem will be used to retrieve file contents.

Parse

You can parse the contents of a file by passing its path to parse(). This will attempt to retrieve the file's contents and resolve any external references.

It returns a PHP object that represents the OAS document structure that can be used in code.

$document = $openAPI->parse('/path/to/my-oas.json');

$document->openapi(); // 3.1.0

Validate

You can directly validate the contents of a file against the official OpenAPI JSON-schema descriptions. It returns an array of possible errors that occured during the validation.

$errors = $openAPI->validate('/path/to/my-oas.yaml');

⚠️ Validation for OAS 3.1 does not check any JSON Schemas in your OpenAPI document because it allows you to use any JSON Schema dialect you choose!

Resolve

You can resolve external and internal references. It returns a PHP object with the resolved contents.

$contents = $openAPI->resolve('/path/to/my-oas.json');

$document = new Apiboard\OpenAPI\Structure\Document($contents);

When resolving references the contents will be retrieved from the local fileystem by default. You can override the way file contents is retrieved by passing a custom class that implements the Apiboard\OpenAPI\Contents\Retriever interface.

$customRetriever = new MyCustomRetriever();
$openAPI = new OpenAPI($customRetriever);

$openAPI->resolve('/path/to/my-oas.json');

Circular references are resolved as an internal reference after recursing twice, this is to prevent infinite recursion.

License

The MIT License (MIT). Please see License File for more information.