README

PHP library for reading and processing OpenAPI 3 specifications (JSON / YAML).

PHP ">= 8.1"
Framework‑agnostic
Supports:
- loading OpenAPI specs from .json and .yaml / .yml files,
- listing endpoints with pagination,
- fetching single endpoint details (parameters, request body, responses),
- reading schema definitions from components.schemas,
- searching endpoints by path and summary/description.

Installation

composer require adachsoft/open-api-reader

Requires PHP 8.1 or higher (as defined in composer.json).

Basic usage

The recommended way to use the library is via the built‑in factory OpenApiReaderFactory:

use AdachSoft\OpenApiReader\Factory\OpenApiReaderFactory;

$factory = OpenApiReaderFactory::createDefault();

// Load specification from JSON or YAML file
$reader = $factory->createFromFile(__DIR__ . '/openapi.yaml');

// 1. List endpoints (pagination)
$summary = $reader->getEndpointsSummary(page: 1, limit: 20);

foreach ($summary as $endpointSummaryDto) {
    echo $endpointSummaryDto->method . ' ' . $endpointSummaryDto->path . PHP_EOL;
}

// 2. Get details for a specific endpoint
$detail = $reader->getEndpointDetails('/users/{id}', 'GET');

// 3. Get schema definition
$schema = $reader->getSchema('User');

// 4. Search endpoints by path or description
$results = $reader->search('user');

Supported HTTP methods

When building the endpoint list (getEndpointsSummary), the following HTTP methods are taken into account:

GET
POST
PUT
PATCH
DELETE
OPTIONS
HEAD
TRACE

YAML support

YAML files (*.yaml / *.yml) are supported via the YamlSpecLoader class.

Default behaviour:

If the yaml_parse_file function (PECL yaml extension) is available, it is used to read and parse the YAML file.
If parsing fails or the yaml extension is not installed, the loader:
- tries to locate a neighbouring JSON file with the same name (e.g. openapi.yaml → openapi.json),
- uses JsonSpecLoader as a fallback mechanism.
If neither the YAML file nor the JSON file can be successfully read, a FileNotReadableException is thrown.

This allows the library to work consistently both with and without the yaml extension.

You can also inject a custom YAML parser (e.g. based on another library) by passing a callback as the second argument to YamlSpecLoader.

Architecture overview

Public contract of the library:

AdachSoft\OpenApiReader\OpenApiReaderInterface

Default implementation:

AdachSoft\OpenApiReader\OpenApiReader
created via AdachSoft\OpenApiReader\Factory\OpenApiReaderFactory

Main internal components (marked as @internal, usually not used directly by consumers):

Specification loaders:
- Loader\SpecLoaderInterface
- Loader\JsonSpecLoader
- Loader\YamlSpecLoader
Data cleaning:
- Cleaner\DataCleanerInterface
- Cleaner\EmptyValueDataCleaner (recursively removes null values and empty arrays [])
Builders:
- Builder\EndpointBuilderInterface / Builder\EndpointBuilder
- Builder\SchemaBuilderInterface / Builder\SchemaBuilder
DTOs and collections:
- Dto\EndpointSummaryDto, Dto\EndpointDetailDto, Dto\SchemaDefinitionDto, Dto\ParameterDto, Dto\RequestBodyDto, Dto\ResponseDto
- Collection\EndpointSummaryCollection, Collection\ParameterCollection, Collection\ResponseCollection, Collection\OpenApiSpecDataCollection

As a consumer, you should typically use:

OpenApiReaderFactory to create a reader instance,
OpenApiReaderInterface / OpenApiReader as the main API.

Advanced configuration

You can build a custom configuration (e.g. your own cleaner or loaders) and pass it into the factory:

use AdachSoft\OpenApiReader\Builder\EndpointBuilder;
use AdachSoft\OpenApiReader\Builder\SchemaBuilder;
use AdachSoft\OpenApiReader\Cleaner\EmptyValueDataCleaner;
use AdachSoft\OpenApiReader\Factory\OpenApiReaderFactory;
use AdachSoft\OpenApiReader\Loader\JsonSpecLoader;
use AdachSoft\OpenApiReader\Loader\YamlSpecLoader;

$dataCleaner = new EmptyValueDataCleaner();
$jsonLoader = new JsonSpecLoader();
$yamlLoader = new YamlSpecLoader($jsonLoader); // default parser uses yaml_parse_file if available

$factory = new OpenApiReaderFactory(
    specLoaders: [$jsonLoader, $yamlLoader],
    endpointBuilder: new EndpointBuilder($dataCleaner),
    schemaBuilder: new SchemaBuilder($dataCleaner),
);

$reader = $factory->createFromFile(__DIR__ . '/openapi.yaml');

If you need full control over YAML parsing, you can inject your own parser callback:

use AdachSoft\OpenApiReader\Loader\YamlSpecLoader;

$parser = static function (string $filePath): array {
    // parse YAML using your preferred library
};

$yamlLoader = new YamlSpecLoader($jsonLoader, $parser);

Tests and quality

The project includes a PHPUnit 13 test suite:

vendor/bin/phpunit

Additional tools:

PHPStan (static analysis):
```
composer run stan
```

PHP CS Fixer (code style):

composer run cs:check   # check only
composer run cs:fix     # apply fixes

License

This project is released under the MIT license (see composer.json).

adachsoft / open-api-reader

Maintainers

Package info

Statistics

Security