cebe/php-openapi

The php-openapi CLI tool allows you to validate OpenAPI 3.0.x files against the official schema and convert between JSON and YAML formats. It supports reading from files or STDIN and writing to files or STDOUT.

# Validate a YAML file
./bin/php-openapi validate input.yaml

# Convert a JSON file to a single YAML file with external references inlined
./bin/php-openapi inline input.json output.yaml

When using readFromJsonFile() or readFromYamlFile(), you can control how $resolveReferences behaves. This determines if Reference objects are replaced by the actual objects they point to.

Supported values for $resolveReferences:

• true (default): Resolves all references.
• false: Does not resolve any references.
• 'inline': Only resolves references to external files.
• 'all': Resolves all references except recursive references.

use cebe\openapi\Reader;

// Resolve only external file references
$spec = Reader::readFromYamlFile('spec.yaml', OpenApi::class, 'inline');

// Resolve all non-recursive references
$spec = Reader::readFromYamlFile('spec.yaml', OpenApi::class, 'all');

// Do not resolve any references
$spec = Reader::readFromYamlFile('spec.yaml', OpenApi::class, false);

You can validate a Callback object against the OpenAPI specification using the validate() method. This checks both the callback structure itself and the underlying PathItem object.

If validate() returns false, you can retrieve a list of specific validation errors using getErrors(). Errors may include the JSON pointer position of the error within the document.

if (!$callback->validate()) {
    foreach ($callback->getErrors() as $error) {
        echo "Error: " . $error . PHP_EOL;
    }
}

If you need to access the original array data (the raw YAML/JSON input) used to instantiate the Reference object, use getRawSpecData(). This is useful for debugging or manual inspection of the $ref key.

$rawData = $reference->getRawSpecData();
// Returns ['$ref' => '...']

You can check if a Reference object is valid according to the OpenAPI specification by calling validate(). This checks if the $ref value is a valid JSON pointer and if the object contains only the allowed $ref property.

If validate() returns false, you can retrieve the specific error messages using getErrors().

if (!$reference->validate()) {
    $errors = $reference->getErrors();
    foreach ($errors as $error) {
        echo "Validation error: $error\n";
    }
}

Use Writer::writeToYaml() to convert an object implementing SpecObjectInterface (such as an OpenApi instance) into a YAML-formatted string. The output is configured to dump objects as maps and empty arrays as sequences to maintain OpenAPI compatibility.

use cebe\openapi\Writer;

// Assuming $openapi is an instance of cebe\openapi\spec\OpenApi
$yamlString = Writer::writeToYaml($openapi);

Use Reader::readFromJson() or Reader::readFromYaml() to instantiate OpenAPI spec objects directly from raw strings. By default, these methods return an instance of cebe\openapi\spec\OpenApi. If you are working with sub-sections of a specification, you can pass a different class name as the $baseType argument, provided it implements SpecObjectInterface.

use cebe\openapi\Reader;
use cebe\openapi\spec\OpenApi;

// From a JSON string
$spec = Reader::readFromJson($jsonString);

// From a YAML string
$spec = Reader::readFromYaml($yamlString);

// Specifying a custom base type for sub-sections
$pathItem = Reader::readFromYaml($yamlString, PathItem::class);

The cebe\openapi\spec\PathItem class represents an OpenAPI Path Item object, which describes the operations (GET, POST, etc.) available on a single path.

Key properties available on a PathItem instance include:

• summary: A short summary of the path.
• description: A detailed description of the path.
• Operations: get, put, post, delete, options, head, patch, and trace (each returns an Operation|null).
• servers: An array of Server objects.
• parameters: An array of Parameter or Reference objects.

Note: A Path Item may be empty due to ACL constraints; the path remains exposed in documentation, but operations and parameters may be unknown.