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:

1. If the yaml_parse_file function (PECL yaml extension) is available, it is used to read and parse the YAML file.
2. 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.
3. 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).