PHP OpenAPI

https://github.com/cebe/php-openapi
Admin
PHP OpenAPI is a library for reading and writing OpenAPI 3.0.x YAML and JSON files with PHP object...
Tokens:72,751
Snippets:500
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### JsonPointer usage example

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Example of creating a JsonPointer, appending a path, getting the parent, and evaluating against a raw spec document.

```php
use cebe\openapi\json\JsonPointer;

$pointer = new JsonPointer('/components/schemas/Foo');
echo $pointer->append('properties')->getPointer();  // /components/schemas/Foo/properties
echo $pointer->parent()->getPointer();              // /components/schemas
$value = $pointer->evaluate($rawSpec);              // the Foo schema array
```

--------------------------------

### Read OpenAPI YAML and resolve references

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-paths.md

Usage example showing how to read an OpenAPI YAML file, get a path item, check for a reference, print the reference string, resolve references, and get conflict errors.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromJsonFile(realpath('openapi.yaml'), OpenApi::class, false);
$item = $openapi->paths->getPath('/pets');
if ($item->getReference() !== null) {
    echo $item->getReference()->getReference(); // external path item $ref
    $item->resolveReferences();                  // merges referenced properties
}
    $errors = $item->getErrors();               // conflict errors, if any
```

--------------------------------

### Usage example for Writer::writeToYamlFile

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/writer.md

Example of calling Writer::writeToYamlFile with an OpenAPI object and a file path. Requires importing the Writer class.

```php
use cebe\openapi\Writer;

Writer::writeToYamlFile($openapi, 'output/openapi.yaml');
```

--------------------------------

### Usage example: reading and validating an OpenAPI file

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-base-object.md

Shows how to read an OpenAPI file, validate it, and access document context and extensions. The example prints validation errors if any, then outputs the pointer for the '/pets' path and the value of the 'x-company' extension if present.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromJsonFile(realpath('openapi.json'));

$valid = $openapi->validate();
if (!$valid) {
    foreach ($openapi->getErrors() as $error) {
        echo $error, "\n";
    }
}

// document context is available after reading
echo $openapi->paths->getPath('/pets')->getDocumentPosition()->getPointer(); // /paths/~1pets
echo $openapi->getExtensions()['x-company'] ?? null;
```

--------------------------------

### Read OpenAPI JSON and access/add paths

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-paths.md

Usage example showing how to read an OpenAPI JSON file, check for a path, get a path item, count its HTTP operations, and add a new path item using array-style access and the PathItem constructor.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromJsonFile(realpath('openapi.json'));

// array-style access to paths (ArrayAccess)
if ($openapi->paths->hasPath('/pets')) {
    $pathItem = $openapi->paths->getPath('/pets');
    echo count($pathItem->getOperations()); // number of HTTP operations
}

$newItem = new \cebe\openapi\spec\PathItem([
    'summary' => 'pet store endpoint',
    'get' => [
        'responses' => [
            '200' => ['description' => 'ok'],
        ],
    ],
]);
$openapi->paths->addPath('/pets', $newItem);
```

--------------------------------

### Manual usage example

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reference-context.md

Example of manually resolving references using ReferenceContext.

```APIDOC
## Manual usage example

### Description
Example of resolving references manually when data was loaded without a context attached.

### Code
```php
use cebe\openapi\Reader;
use cebe\openapi\ReferenceContext;

$openapi = Reader::readFromYamlFile(realpath('api/openapi.yaml'), OpenApi::class, false); // no auto-resolve
$openapi->resolveReferences(
    new ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml')
);
```

```php
use cebe\openapi\ReferenceContext;

// non-throwing resolution: collect failures via Reference::getErrors() instead
$context = new ReferenceContext($openapi, realpath('api/openapi.yaml'));
$context->throwException = false;
$context->mode = ReferenceContext::RESOLVE_MODE_INLINE;
$openapi->resolveReferences($context);
```
```

--------------------------------

### Create a ReferenceContext instance

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reference-context.md

Example of instantiating ReferenceContext with an absolute URI. The base spec object and URI are required; the cache is optional.

```php
use cebe\openapi\ReferenceContext;

$context = new ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml');
```

--------------------------------

### Create OpenAPI Info and Server objects

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-meta.md

Shows how to instantiate Info, Contact, License, and Server objects with the cebe\openapi\spec namespace. The Server example includes URL variables with a default and enum values.

```php
use cebe\openapi\spec\Info;
use cebe\openapi\spec\Contact;
use cebe\openapi\spec\License;

$openapi->info = new Info([
    'title' => 'Pet Store',
    'version' => '1.0.0',
    'contact' => new Contact(['email' => 'mail@example.com']),
    'license' => new License(['name' => 'MIT']),
]);

$openapi->servers = [
    new \cebe\openapi\spec\Server([
        'url' => 'https://{environment}.example.com/v1',
        'variables' => [
            'environment' => [
                'default' => 'api',
                'enum' => ['api', 'staging'],
            ],
        ],
    ]),
];
```

--------------------------------

### Usage example for Reader::readFromYamlFile

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reader.md

Reads a remote YAML spec and prints each path. The `$openapi->paths` property is iterated as an array of path definitions.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromYamlFile('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml');
foreach ($openapi->paths as $path => $definition) {
    echo $path, "\n";
}
```

--------------------------------

### getExtensions() method signature

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-base-object.md

Returns all stored properties whose key starts with `x-`. Available since version 1.6.0.

```php
/**
 * Returns extension properties with `x-` prefix.
 * @see https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#specificationExtensions
 * @return array<string, mixed>
 * @since 1.6.0
 */
public function getExtensions(): array
```

--------------------------------

### JsonReference usage example

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Shows how to create a JsonReference from a reference URI, access its parts, and handle a missing $ref member with MalformedJsonReferenceObjectException.

```php
use cebe\openapi\json\JsonReference;

$ref = JsonReference::createFromReference('http://example.com/example.json#/foo/bar');
echo $ref->getDocumentUri();   // http://example.com/example.json
echo $ref->getJsonPointer()->getPointer(); // /foo/bar
echo $ref->getReference();     // http://example.com/example.json#/foo/bar

try {
    JsonReference::createFromJson('{}');
} catch (\cebe\openapi\json\MalformedJsonReferenceObjectException $e) {
    // JSON Reference Object must contain the "$ref" member.
}
```

--------------------------------

### Manual usage example: non-throwing resolution with inline mode

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reference-context.md

Shows how to resolve references without throwing exceptions, collecting failures via Reference::getErrors(). Sets throwException to false and mode to RESOLVE_MODE_INLINE.

```php
use cebe\openapi\ReferenceContext;

// non-throwing resolution: collect failures via Reference::getErrors() instead
$context = new ReferenceContext($openapi, realpath('api/openapi.yaml'));
$context->throwException = false;
$context->mode = ReferenceContext::RESOLVE_MODE_INLINE;
$openapi->resolveReferences($context);
```

--------------------------------

### Usage example with SpecObjectInterface

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/interfaces.md

Shows how to use the SpecObjectInterface to validate an OpenAPI object and print the result. Requires the cebe/php-openapi package.

```php
use cebe\openapi\SpecObjectInterface;
use cebe\openapi\DocumentContextInterface;

function printSpecSummary(SpecObjectInterface $obj) {
    echo $obj->validate() ? 'valid' : 'invalid';
}
```

--------------------------------

### get method signature

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reference-context.md

Defines the get method for retrieving a cached value by reference key and type qualifier. Returns null when absent.

```php
public function get($ref, $type)
```

--------------------------------

### JsonPointer::__construct

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Constructs a new JsonPointer instance from a string. The string must be either an empty string (for the whole document) or start with '/'.

```APIDOC
## [JsonPointer] __construct

### Description
Constructs a new JSON Pointer from a string. The pointer must be an empty string (for the document root) or start with '/' and follow RFC 6901 syntax.

### Method
__construct

### Endpoint
`cebe\openapi\json\JsonPointer::__construct(string $pointer)`

### Parameters
- `$pointer` (string) - Required - The JSON Pointer string. Must be either '' or a string starting with '/' matching `~^(/[^/]*)*$~`.

### Throws
- `cebe\openapi\json\InvalidJsonPointerSyntaxException` if the pointer is invalid.

### Example
```php
$pointer = new JsonPointer('/components/schemas/Foo');
```
```

--------------------------------

### Create and assign an Operation object

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-operation.md

Creates an Operation object with operationId, summary, responses, and parameters, then assigns it to the GET path of '/pets' in the OpenAPI document.

```php
use cebe\openapi\spec\Operation;
use cebe\openapi\spec\Responses;

$op = new Operation([
    'operationId' => 'listPets',
    'summary' => 'List all pets',
    'responses' => new Responses([
        '200' => ['description' => 'A list of pets'],
    ]),
    'parameters' => [
        ['name' => 'limit', 'in' => 'query', 'schema' => ['type' => 'integer']],
    ],
]);

$openapi->paths->getPath('/pets')->get = $op;
```

--------------------------------

### Manual usage example: resolve references with explicit context

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reference-context.md

Shows how to resolve references when data was loaded via Reader::readFromJson or readFromYaml without auto-resolve. Provides a ReferenceContext with a base URI.

```php
use cebe\openapi\Reader;
use cebe\openapi\ReferenceContext;

$openapi = Reader::readFromYamlFile(realpath('api/openapi.yaml'), OpenApi::class, false); // no auto-resolve
$openapi->resolveReferences(
    new ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml')
);
```

--------------------------------

### Writing API Description with Prepared Objects

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Since version 1.2.0, the OpenApi constructor accepts prepared objects instead of arrays. This example uses new Info() and new PathItem() instances. The output JSON is not shown here.

```php
use cebe\openapi\spec\OpenApi;
use cebe\openapi\spec\PathItem;
use cebe\openapi\spec\Info;


// create base API Description
$openapi = new OpenApi([
    'openapi' => '3.0.2',
    'info' => new Info([
        'title' => 'Test API',
        'version' => '1.0.0',
    ]),
    'paths' => [
        '/test' => new PathItem([
            'description' => 'something'
        ]),
    ],
]);
$json = \cebe\openapi\Writer::writeToJson($openapi);
```

--------------------------------

### Reader::readFromYaml usage example

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reader.md

Example usage of Reader::readFromYaml to instantiate an Operation object from a YAML sub-section. The YAML string is parsed and the summary property is accessed.

```php
use cebe\openapi\Reader;
use cebe\openapi\spec\Operation;

$yaml = "summary: hello\nresponses:\n  '200':\n    description: ok\n";
// instantiate an Operation object from a sub-section
$operation = Reader::readFromYaml($yaml, Operation::class);
echo $operation->summary; // hello
```

--------------------------------

### Read OpenAPI components with cebe\openapi\Reader

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-components.md

Reads an OpenAPI JSON file and accesses components by name. The example shows retrieving a schema and a security scheme from the components map.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromJsonFile(realpath('openapi.json'));
$components = $openapi->components;

// named map access to components
$mySchema = $components->schemas['Foo'];
$myScheme = $components->securitySchemes['bearerAuth'];
```

--------------------------------

### Serialize OpenAPI object to YAML

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/writer.md

Example usage of Writer::writeToYaml to serialize an OpenAPI object to YAML and echo the result.

```php
use cebe\openapi\Writer;

$yaml = Writer::writeToYaml($openapi);
echo $yaml;
```

--------------------------------

### JsonPointer constructor

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Constructor for JsonPointer. Requires a pointer string that is either empty (whole document) or starts with '/'. Throws InvalidJsonPointerSyntaxException for invalid syntax.

```php
/**
 * JSON Pointer constructor.
 * @param string $pointer The JSON Pointer.
 * Must be either an empty string (for referencing the whole document), or a string starting with `/`.
 * @throws InvalidJsonPointerSyntaxException in case an invalid JSON pointer string is passed
 */
public function __construct(string $pointer)
```

--------------------------------

### Read a component schema and its properties

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Example of reading a component schema `Foo` and its property `message` from the `$openapi` object. The YAML defines the spec with a `/foo` path.

```yaml
openapi: 3.0.0
info:
  title: Test API
  version: 1.0.0
paths:
  /foo:
    put:
      description: create foo
      responses:
        '200':
          description: request succeeded          
components:  
  schemas:
    Foo:
      description: This is an description
      type: object
      properties:
        message:
          type: string
        code:
          type: number
```

```php
# read a component schema
$foo = $openapi->components->schemas['Foo'];

# read a property of schema
$foo->properties['message']
```

--------------------------------

### Write OpenAPI JSON with Writer::writeToJson

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-openapi.md

Create an OpenApi object programmatically with OpenApi, Info, and PathItem, then serialize it to JSON using Writer::writeToJson. The example shows setting the openapi version, info, and a path definition.

```php
use cebe\openapi\spec\OpenApi;
use cebe\openapi\spec\PathItem;
use cebe\openapi\spec\Info;
use cebe\openapi\Writer;

$openapi = new OpenApi([
    'openapi' => '3.0.2',
    'info' => new Info([
        'title' => 'Test API',
        'version' => '1.0.0',
    ]),
    'paths' => [
        '/test' => new PathItem([ 'description' => 'something' ]),
    ],
]);

$openapi->paths['/test']->get = /* … */;

$json = Writer::writeToJson($openapi);
```

--------------------------------

### Manually Resolving References with ReferenceContext

Source: https://github.com/cebe/php-openapi/blob/master/README.md

If data is loaded differently, you can manually resolve references by giving a context. The example passes a new ReferenceContext with the openapi object and a base URL.

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

--------------------------------

### Read OpenAPI Description from YAML file or URL

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Reads an OpenAPI description from a YAML file using `Reader::readFromYamlFile`. Can also read from a URL, as shown with a remote example.

```php
use cebe\openapi\Reader;

// realpath is needed for resolving references with relative Paths or URLs
$openapi = Reader::readFromYamlFile(realpath('openapi.yaml'));
// you may also specify the URL to your API Description file
$openapi = Reader::readFromYamlFile('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore-expanded.yaml');
```

--------------------------------

### Catch php-openapi exceptions (IOException, UnresolvableReferenceException, TypeErrorException)

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/errors.md

Shows how to catch custom exceptions when reading an OpenAPI file. IOException is thrown for unreadable files, UnresolvableReferenceException for broken references, and TypeErrorException for malformed spec data. The example uses fully qualified exception names and writes messages to STDERR.

```php
try {
    $openapi = \cebe\openapi\Reader::readFromJsonFile(realpath('openapi.json'));
} catch (\cebe\openapi\exceptions\IOException $e) {
    fwrite(STDERR, 'unreadable file: ' . $e->fileName . "\n");
} catch (\cebe\openapi\exceptions\UnresolvableReferenceException $e) {
    fwrite(STDERR, 'broken reference at ' . $e->context . ': ' . $e->getMessage() . "\n");
} catch (\cebe\openapi\exceptions\TypeErrorException $e) {
    fwrite(STDERR, 'malformed spec data: ' . $e->getMessage() . "\n");
}
```

--------------------------------

### CLI help output

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Running `vendor/bin/php-openapi help` displays usage for commands like validate, convert, inline, and help, along with options like --read-json and --silent. Includes exit codes and reference resolution flags.

```text
$ vendor/bin/php-openapi help
PHP OpenAPI 3 tool
------------------
by Carsten Brandt <mail@cebe.cc>

Usage:
  php-openapi <command> [<options>] [input.yml|input.json] [output.yml|output.json]

  The following commands are available:

    validate   Validate the API Description in the specified input file against the OpenAPI v3.0 schema.
               Note: the validation is performed in two steps. The results are composed of
                (1) structural errors found while reading the API Description file, and
                (2) violations of the OpenAPI v3.0 schema.

               If no input file is specified input will be read from STDIN.
               The tool will try to auto-detect the content type of the input, but may fail
               to do so. You may specify --read-yaml or --read-json to force the file type.

               Exits with code 2 on validation errors, 1 on other errors and 0 on success.

    convert    Convert a JSON or YAML input file to JSON or YAML output file.

               If no input file is specified input will be read from STDIN.
               If no output file is specified output will be written to STDOUT.
               The tool will try to auto-detect the content type of the input and output file, but may fail
               to do so. You may specify --read-yaml or --read-json to force the input file type.
               and --write-yaml or --write-json to force the output file type.

               By default all references are resolved (replaced with the object referred to). You can control
               handling of references with the following arguments:

               --resolve-none      Do not resolve references.
               --resolve-external  Only resolve references that point to external files.
                                   This process is often referred to as "inlining".
               --resolve-all       Resolve all references (default).
                                   Recursive pointers will stay references.

    inline     Convert a JSON or YAML input file to JSON or YAML output file and
               resolve all external references. The output will be a single API Description file.
               This is a shortcut for calling convert --resolve-external.

    help       Shows this usage information.

  Options:

    --read-json   force reading input as JSON. Auto-detect if not specified.
    --read-yaml   force reading input as YAML. Auto-detect if not specified.
    --write-json  force writing output as JSON. Auto-detect if not specified.
    --write-yaml  force writing output as YAML. Auto-detect if not specified.
    -s, --silent  silent mode. Will hide all success/information messages and only print errors.

```

--------------------------------

### Reader::readFromJson usage example

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reader.md

Example of using `Reader::readFromJson` to read a JSON OpenAPI spec and access a property.

```php
use cebe\openapi\Reader;

$spec = Reader::readFromJson('{"openapi":"3.0.2","info":{"title":"Test","version":"1.0.0"},"paths":{}}');
echo $spec->openapi; // 3.0.2

```

--------------------------------

### get

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/reference-context.md

Retrieves a cached value from the reference context cache.

```APIDOC
## get($ref, $type)

### Description
Retrieves a cached value from the reference context cache for the given reference key and type qualifier. Returns `null` if the value is not present.

### Method
get

### Signature
```php
public function get($ref, $type)
```

### Parameters
- **$ref** (string) - Required - Cache key.
- **$type** (string|null) - Required - Type qualifier.

### Return
Cached value or `null` when absent.
```

--------------------------------

### setContext() and getContext() methods

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-reference.md

Attaches and retrieves the resolution context. getContext() returns null if no context is set.

```php
/**
 * @param ReferenceContext $context
 */
public function setContext(ReferenceContext $context)

/**
 * @return ReferenceContext
 */
public function getContext() : ?ReferenceContext
```

--------------------------------

### Create Responses object with Response definitions

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-responses.md

Shows how to create a Responses object with a '200' Response and a 'default' response, then access and add responses. The '200' response includes a JSON schema.

```php
use cebe\openapi\spec\Responses;
use cebe\openapi\spec\Response;

$responses = new Responses([
    '200' => new Response([
        'description' => 'request succeeded',
        'content' => [
            'application/json' => [
                'schema' => ['type' => 'object'],
            ],
        ],
    ]),
    'default' => ['description' => 'unexpected error'],
]);

echo $responses->getResponse('200')->description;
$responses->addResponse('404', new Response(['description' => 'not found']));
```

--------------------------------

### Reading API Description Files with Reference Resolution

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Shows how to read JSON or YAML files using Reader::readFromJsonFile and Reader::readFromYamlFile. The mode can be RESOLVE_MODE_ALL or RESOLVE_MODE_INLINE, with ALL resolving all references and INLINE only external references. Requires an absolute URL or file path.

```php
use cebe\openapi\Reader;
use cebe\openapi\spec\OpenAPI;
use cebe\openapi\ReferenceContext;

// there are two different modes for resolving references:
// ALL: resolve all references, which will result in a large description with a lot of repetition
// but no references (except if there are recursive references, these will stop at some level)
$mode = ReferenceContext::RESOLVE_MODE_ALL;
// INLINE: only references to external files are resolved, references to places in the current file
// are still Reference objects.
$mode = ReferenceContext::RESOLVE_MODE_INLINE;

// an absolute URL or file path is needed to allow resolving external references
$openapi = Reader::readFromJsonFile('https://www.example.com/api/openapi.json', OpenAPI::class, $mode);
$openapi = Reader::readFromYamlFile('https://www.example.com/api/openapi.yaml', OpenAPI::class, $mode);
```

--------------------------------

### Resolve references with ReferenceContext and validate

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-reference.md

Creates a ReferenceContext with a base URL, sets throwException to false to collect errors, resolves all references, then validates the document. If validation fails, prints each error to STDERR.

```php
use cebe\openapi\ReferenceContext;

$context = new ReferenceContext($openapi, 'https://www.example.com/api/openapi.yaml');
$context->throwException = false; // collect errors instead of throwing
$openapi->resolveReferences($context);

if (!$openapi->validate()) {
    foreach ($openapi->getErrors() as $error) {
        fwrite(STDERR, $error . "\n");
    }
}
```

--------------------------------

### Create and inspect a Schema object

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-schema.md

Creates a Schema object with properties and required fields, then accesses a property's type. Outputs 'string'.

```php
use cebe\openapi\spec\Schema;

$foo = new Schema([
    'type' => 'object',
    'properties' => [
        'message' => ['type' => 'string'],
        'code' => ['type' => 'number'],
    ],
    'required' => ['message'],
]);
echo $foo->properties['message']->type; // string
```

--------------------------------

### Iterate over responses from an OpenAPI file

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-responses.md

Reads an OpenAPI JSON file and iterates over the responses of the GET operation for the '/pets' path, printing each status code and description.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromJsonFile(realpath('openapi.json'));
$responses = $openapi->paths->getPath('/pets')->get->responses;

foreach ($responses as $status => $response) {
    echo $status, ': ', $response->description, "\n";
}
```

--------------------------------

### Create a Callback object with cebe\openapi\spec\Callback

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-components.md

Instantiates a Callback with a callback URL expression and a POST operation. The getUrl() method returns the callback URL expression, and getRequest()->getOperations() returns the operations map.

```php
use cebe\openapi\spec\Callback;

$callback = new Callback([
    '{$request.body#/callbackUrl}' => [
        'post' => [
            'responses' => [
                '200' => ['description' => 'callback received'],
            ],
        ],
    ],
]);
echo $callback->getUrl();                // {$request.body#/callbackUrl}
echo $callback->getRequest()->getOperations(); // ['post' => Operation]
```

--------------------------------

### setReferenceContext / setDocumentContext method signatures

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-paths.md

Method signatures for setting reference and document context on a PathItem. The $ref Reference gets document context at $jsonPointer->append('$ref').

```php
public function setReferenceContext(ReferenceContext $context)

public function setDocumentContext(SpecObjectInterface $baseDocument, JsonPointer $jsonPointer)
```

--------------------------------

### Write OpenAPI object to JSON file

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/writer.md

Example usage of Writer::writeToJsonFile to write an OpenAPI object to a JSON file, catching IOException and writing an error message to STDERR.

```php
use cebe\openapi\Writer;

try {
    Writer::writeToJsonFile($openapi, 'output/openapi.json');
} catch (\cebe\openapi\exceptions\IOException $e) {
    fwrite(STDERR, 'could not write: ' . $e->getMessage());
}
```

--------------------------------

### Read OpenAPI from JSON file

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-meta.md

Demonstrates using Reader::readFromJsonFile to load an OpenAPI specification from a JSON file. Shows how to access the info title, iterate over security requirements, and access a security scheme's type.

```php
use cebe\openapi\Reader;

$openapi = Reader::readFromJsonFile(realpath('openapi.json'));

echo $openapi->info->title;
foreach ($openapi->security as $index => $requirement) {
    // each $requirement is a SecurityRequirement object
}
echo $openapi->components->securitySchemes['bearerAuth']->type; // http
```

--------------------------------

### Parameter class definition

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-operation.md

Defines the Parameter class extending SpecBaseObject with properties for a single operation parameter, including name, location, description, flags, serialization settings, schema, example, and content.

```php
/**
 * Describes a single operation parameter.
 *
 * @link https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#parameterObject
 *
 * @property string $name
 * @property string $in
 * @property string $description
 * @property bool $required
 * @property bool $deprecated
 * @property bool $allowEmptyValue
 *
 * @property string $style
 * @property boolean $explode
 * @property boolean $allowReserved
 * @property Schema|Reference|null $schema
 * @property mixed $example
 * @property Example[] $examples
 *
 * @property MediaType[] $content
 */
class Parameter extends SpecBaseObject
```

--------------------------------

### Callback constructor

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-components.md

Constructor for the Callback object. Expects an array with exactly one entry; otherwise records the error 'Callback object must have exactly one URL.' and returns. The single key is stored as the callback URL and the value is wrapped in a PathItem.

```php
/**
 * Create an object from spec data.
 * @param array $data spec data read from YAML or JSON
 * @throws TypeErrorException in case invalid data is supplied.
 */
public function __construct(array $data)
{
    if (count($data) !== 1) {
        $this->_errors[] = 'Callback object must have exactly one URL.';
        return;
    }
    $this->_pathItem = new PathItem(reset($data));
    $this->_url = key($data);
}

```

--------------------------------

### Paths __construct method

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-paths.md

Constructor for Paths. Accepts an array mapping path strings to PathItem instances, plain arrays, or null. Each value is stored as-is, wrapped into a PathItem, or accepted when already a PathItem. Throws cebe\openapi\exceptions\TypeErrorException with message 'Path MUST be either array or PathItem object, "<type>" given' for any other value type.

```php
/**
 * Create an object from spec data.
 * @param (PathItem|array|null)[] $data spec data read from YAML or JSON
 * @throws TypeErrorException in case invalid data is supplied.
 */
public function __construct(array $data)
```

--------------------------------

### JsonReference instance methods

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Defines __clone, getJsonPointer, getDocumentUri, getReference, and jsonSerialize methods. jsonSerialize returns an object with a $ref key for json_encode.

```php
public function __clone()

public function getJsonPointer(): JsonPointer

/**
 * @return string returns the URI of the referenced JSON document without the fragment (JSON Pointer) part.
 */
public function getDocumentUri(): string

/**
 * @return string returns the JSON Pointer in URI format.
 */
public function getReference(): string

/**
 * Specify data which should be serialized to JSON
 * @link https://php.net/manual/en/jsonserializable.jsonserialize.php
 * @return mixed data which can be serialized by <b>json_encode</b>,
 * which is a value of any type other than a resource.
 */
#[\ReturnTypeWillChange]
public function jsonSerialize() //: mixed
```

--------------------------------

### Response map accessors

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-responses.md

Methods to check, get, add, remove, and list responses by HTTP status code. getResponse returns Response|Reference|null, getResponses returns an array keyed by status code.

```php
/**
 * @param string $statusCode HTTP status code
 * @return bool
 */
public function hasResponse($statusCode): bool

/**
 * @param string $statusCode HTTP status code
 * @return Response|Reference|null
 */
public function getResponse($statusCode)

/**
 * @param string $statusCode HTTP status code
 * @param Response|Reference $response
 */
public function addResponse($statusCode, $response): void

/**
 * @param string $statusCode HTTP status code
 */
public function removeResponse($statusCode)

/**
 * @return (Response|Reference|null)[]
 */
public function getResponses(): array
```

--------------------------------

### Writing API Description with Arrays

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Creates an OpenAPI object using nested arrays for the info and paths, then outputs JSON with Writer::writeToJson. The resulting JSON is shown with a different version field (3.0.0) than the input.

```php
use cebe\openapi\spec\OpenApi;
use cebe\openapi\spec\PathItem;

// create base API Description
$openapi = new OpenApi([
    'openapi' => '3.0.2',
    'info' => [
        'title' => 'Test API',
        'version' => '1.0.0',
    ],
    'paths' => [],
]);
// manipulate description as needed
$openapi->paths['/test'] = new PathItem([
    'description' => 'something'
]);
// ...

$json = \cebe\openapi\Writer::writeToJson($openapi);
```

```json
{
    "openapi": "3.0.0",
    "info": {
        "title": "Test API",
        "version": "1.0.0"
    },
    "paths": {
        "/test": {
            "description": "something"
        }
    }
}
```

--------------------------------

### JsonPointer __toString, getPointer, getPath

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Methods to get the raw pointer string and the decoded path array. getPath returns an array of decoded path segments; empty pointer returns empty array.

```php
public function __toString()

/**
 * @return string returns the JSON Pointer.
 */
public function getPointer(): string

/**
 * @return array the JSON pointer path as array.
 */
public function getPath(): array
```

--------------------------------

### Parameter constructor with defaults

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-operation.md

Sets default values for 'style' and 'explode' based on the 'in' and 'style' fields, following the OpenAPI specification. When 'in' is query or cookie, defaults to 'form' with explode=true; path or header defaults to 'simple' with explode=false. If 'style' is provided, explode defaults to true only when style is 'form'.

```php
public function __construct(array $data)
{
    if (isset($data['in'])) {
        // Spec: Default values (based on value of in):
        // for query - form;
        // for path - simple;
        // for header - simple;
        // for cookie - form.
        switch ($data['in']) {
            case 'query':
            case 'cookie':
                $this->_attributeDefaults['style'] = 'form';
                $this->_attributeDefaults['explode'] = true;
                break;
            case 'path':
            case 'header':
                $this->_attributeDefaults['style'] = 'simple';
                $this->_attributeDefaults['explode'] = false;
                break;
        }
    }
    if (isset($data['style'])) {
        // Spec: When style is form, the default value is true. For all other styles, the default value is false.
        $this->_attributeDefaults['explode'] = ($data['style'] === 'form');
    }
    parent::__construct($data);
}
```

--------------------------------

### cebe\openapi\SpecBaseObject

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-base-object.md

Documentation for the abstract base class `cebe\openapi\SpecBaseObject`, including its constructor and abstract methods.

```APIDOC
## Constructor: `__construct(array $data)`

### Description
Creates a spec object from raw spec data (decoded JSON/YAML). Validates and stores declared properties according to the `attributes()` map; undeclared keys are kept as additional properties.

### Method
Constructor

### Signature
`public function __construct(array $data)`

### Parameters
- **$data** (array) - Required - Raw associative spec data read from YAML or JSON.

### Behavior
- Walks `attributes()` and validates/stores each declared property.
- Boolean type mismatches and string-array element mismatches are recorded as errors (not thrown); the object fails `validate()`.
- Invalid map key types throw `TypeErrorException`.
- Undeclared keys are stored as additional properties (e.g., `x-*` extensions).

### Throws
- `cebe\openapi\exceptions\TypeErrorException` - On invalid/illegal data shape (e.g., wrong `additionalProperties` type in `Schema`).
```

```APIDOC
## Abstract Method: `attributes()`

### Description
Returns the map of available attributes for this spec object. Each entry maps a property name to a type token.

### Method
Abstract method

### Signature
`abstract protected function attributes(): array`

### Returns
- **array** - Map of `property name => type token`. Type tokens are `Type::*` constants, a class name (nested object), a one-element array `[itemType]` (list), or a two-element array `[Type::STRING, valueType]` (map).
```

```APIDOC
## Abstract Method: `performValidation()`

### Description
Performs validation on this object against OpenAPI Specification rules. Subclasses add validation errors via `addError()`.

### Method
Abstract method

### Signature
`abstract protected function performValidation()`

### Returns
- **void** - Subclass hook; adds validation errors via `addError()`.
```

--------------------------------

### __construct

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-paths.md

Creates a PathItem object from spec data, handling $ref extraction into a dedicated reference property.

```APIDOC
## PathItem::__construct

### Description
Creates a new PathItem object from spec data read from YAML or JSON. If the data contains a `$ref`, it is extracted into a dedicated `$_ref` property and removed from the data before parsing.

### Method
__construct

### Parameters
#### Constructor Parameters
- **$data** (array) - Required - Spec data for the path item, typically read from YAML or JSON.

### Exceptions
- **\cebe\openapi\exceptions\TypeErrorException** - Thrown in case invalid data is supplied.

### Usage Example
```php
$pathItem = new PathItem([
    'summary' => 'Example path',
    'get' => new Operation([...]),
]);
```
```

--------------------------------

### Schema __construct additionalProperties handling

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-schema.md

Constructor that handles `additionalProperties`. Accepts a boolean, a `Schema`/`Reference` instance, or a plain array (instantiated as a `Schema`). Throws `cebe\openapi\exceptions\TypeErrorException` with message `Schema::$additionalProperties MUST be either boolean or a Schema/Reference object, "<type>" given` for invalid types.

```php
public function __construct(array $data)
{
    if (isset($data['additionalProperties'])) {
        if (is_array($data['additionalProperties'])) {
            $data['additionalProperties'] = $this->instantiate(Schema::class, $data['additionalProperties']);
        } elseif (!($data['additionalProperties'] instanceof Schema || $data['additionalProperties'] instanceof Reference || is_bool($data['additionalProperties']))) {
            $givenType = gettype($data['additionalProperties']);
            if ($givenType === 'object') {
                $givenType = get_class($data['additionalProperties']);
            }
            throw new TypeErrorException(sprintf('Schema::$additionalProperties MUST be either boolean or a Schema/Reference object, "%s" given', $givenType));
        }
    }
    parent::__construct($data);
}
```

--------------------------------

### JsonReference::createFromUri static method

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/json.md

Creates a JsonReference from a URI and an optional JsonPointer. If no pointer is given, an empty pointer references the whole document.

```php
/**
 * Create a JSON Reference instance from an URI and a JSON Pointer.
 * If no JSON Pointer is given this will be interpreted as an empty string JSON pointer, which
 * references the whole document.
 * @param string $uri the URI to the document without a fragment part.
 * @param JsonPointer $jsonPointer
 * @return JsonReference
 */
public static function createFromUri(string $uri, ?JsonPointer $jsonPointer = null): JsonReference
```

--------------------------------

### Reference constructor

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-reference.md

Constructor for the Reference class. Takes spec data and an optional class name for the referenced type. Throws TypeErrorException for invalid data.

```php
/**
 * Create an object from spec data.
 * @param array $data spec data read from YAML or JSON
 * @param string|null $to class name of the type referenced by this Reference
 * @throws TypeErrorException in case invalid data is supplied.
 */
public function __construct(array $data, string $to = null)
```

--------------------------------

### Callback context methods

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-components.md

Context and reference propagation methods for the Callback object. All delegate to the contained PathItem, with the URL as the appended pointer segment.

```php
public function resolveReferences(ReferenceContext $context = null)

public function setReferenceContext(ReferenceContext $context)

public function setDocumentContext(SpecObjectInterface $baseDocument, JsonPointer $jsonPointer)

public function getBaseDocument(): ?SpecObjectInterface

public function getDocumentPosition(): ?JsonPointer

```

--------------------------------

### setDocumentContext, getBaseDocument, getDocumentPosition, getRawSpecData

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-reference.md

These methods manage document context and expose raw data. setDocumentContext stores base document and position without recursion. getBaseDocument returns ?SpecObjectInterface or null, getDocumentPosition returns ?JsonPointer or null, and getRawSpecData returns the raw constructor data as array.

```php
public function setDocumentContext(SpecObjectInterface $baseDocument, JsonPointer $jsonPointer)

public function getBaseDocument(): ?SpecObjectInterface

public function getDocumentPosition(): ?JsonPointer

public function getRawSpecData(): array
```

--------------------------------

### requireProperties(), hasProperty(), hasPropertyValue(), validateEmail(), validateUrl()

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-base-object.md

Protected helper methods for property validation and email/URL checking.

```APIDOC
## requireProperties()

### Description
Adds an error for each missing required property.

### Method
requireProperties()

### Signature
protected function requireProperties(array $names)

### Parameters
- **$names** (array) - Required - List of property names to require.

### Behavior
Adds `"<ClassShortName> is missing required property: <name>"` per missing property.

---

## hasProperty()

### Description
Checks if the object has a property with a non-null value or if the property is defined in the OpenAPI spec. Deprecated since 1.6.0, to be removed in 2.0.0.

### Method
hasProperty()

### Signature
protected function hasProperty(string $name): bool

### Parameters
- **$name** (string) - Required - Property name.

### Return Value
- **bool** – `true` when the property has a non-null value or is defined in the OpenAPI spec.

---

## hasPropertyValue()

### Description
Checks if a property has a non-null value. Does not consider default values. Since 1.6.0.

### Method
hasPropertyValue()

### Signature
protected function hasPropertyValue(string $name): bool

### Parameters
- **$name** (string) - Required - Property name.

### Return Value
- **bool** – `true` when the property has a non-null value.

---

## validateEmail()

### Description
Adds an error unless the property value contains `@`.

### Method
validateEmail()

### Signature
protected function validateEmail(string $property)

### Parameters
- **$property** (string) - Required - Property name to validate.

### Behavior
Adds an error if the property value does not contain `@`.

---

## validateUrl()

### Description
Adds an error unless the property value contains `//`.

### Method
validateUrl()

### Signature
protected function validateUrl(string $property)

### Parameters
- **$property** (string) - Required - Property name to validate.

### Behavior
Adds an error if the property value does not contain `//`.
```

--------------------------------

### getOperations

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-paths.md

Returns all operations defined for this path item, keyed by HTTP method name.

```APIDOC
## PathItem::getOperations

### Description
Returns an array of all operations (get, put, post, etc.) that are defined on this path item, keyed by the method name.

### Method
getOperations

### Return Value
- **Operation[]** - An array of Operation objects, keyed by HTTP method (e.g., 'get', 'post').

### Usage Example
```php
$operations = $pathItem->getOperations();
foreach ($operations as $method => $operation) {
    echo $method . ': ' . get_class($operation) . "\n";
}
```
```

--------------------------------

### Access API Description data in PHP

Source: https://github.com/cebe/php-openapi/blob/master/README.md

Shows how to access OpenAPI object properties like `openapi`, `info->title`, and iterate over `paths`. Properties match the OpenAPI Specification.

```php
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
}
```

--------------------------------

### getExtensions()

Source: https://github.com/cebe/php-openapi/blob/master/_autodocs/api-reference/spec-base-object.md

Returns extension properties with 'x-' prefix. This method allows access to specification extensions defined in the OpenAPI document.

```APIDOC
## getExtensions()

### Description
Returns all stored properties whose key starts with `x-`. This method is available since version 1.6.0 and follows the OpenAPI Specification's extension mechanism.

### Method
N/A - PHP method

### Endpoint
N/A - PHP class method

### Parameters
This method does not take any parameters.

### Return Value
`array<string, mixed>` — associative array of extension properties.

### Usage Example
```php
$extensions = $specBaseObject->getExtensions();
echo $extensions['x-company'] ?? null;
```
```
Tokens:
Raw