PHP code example of on1kel / oas-core

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

on1kel / oas-core example snippets

declare(strict_types=1);

use On1kel\OAS\Contract\Profile\SpecProfile;
use On1kel\OAS\Contract\Profile\FeatureSet;
use On1kel\OAS\Contract\Profile\Enum\Strictness;
use On1kel\OAS\Contract\Validation\NodeValidator;

// Простейшая реализация профиля OAS "3.1" (для примера).
final class OAS31Profile implements SpecProfile
{
    public function id(): string { return '3.1'; }

    public function allowExternalRefs(): bool { return true; }

    public function strictness(): Strictness { return Strictness::Strict; }

    public function normalizeKey(string $nodeType, string $key): string
    {
        // При необходимости приводите ключи к каноническому виду.
        return $key;
    }

    public function features(): FeatureSet
    {
        // Верните набор фич-флагов, если используете.
        return new FeatureSet();
    }

    /** @return array<int, NodeValidator> */
    public function extraValidators(): array
    {
        // Дополнительные валидаторы, специфичные для профиля.
        return [];
    }
}

use On1kel\OAS\Version\ProfileRegistry;
use On1kel\OAS\Version\VersionDetector;

$profiles = (new ProfileRegistry())
    ->register(new OAS31Profile());           // можно регистрировать несколько профилей
$detector = new VersionDetector($profiles);

$raw = json_decode(file_get_contents('openapi.json'), true, 512, JSON_THROW_ON_ERROR);
$profile = $detector->detect($raw);           // вернёт зарегистрированный профиль по полю "openapi"

use On1kel\OAS\Parsing\DocumentParser;
use On1kel\OAS\Ref\DefaultRefFetcher;
use On1kel\OAS\Ref\RefResolver;
use On1kel\OAS\Version\ParseOptions;

// PSR-клиент и фабрики (реализацию предоставьте сами: Guzzle, Symfony HTTP Client и т.п.)
$httpClient = /* Psr\Http\Client\ClientInterface */;
$requestFactory = /* Psr\Http\Message\RequestFactoryInterface */;
$streamFactory = /* Psr\Http\Message\StreamFactoryInterface */;

$fetcher   = new DefaultRefFetcher($httpClient, $requestFactory, $streamFactory);
$resolver  = new RefResolver($fetcher);
$parser    = new DocumentParser($resolver);

$options = (new ParseOptions())
    ->withStrictness($profile->strictness())  // Strict | Lenient
    ->withResolveExternalRefs(true)           // разрешать внешние $ref
    ->withMaxRefDepth(64);                    // защита от циклов/глубины

$baseUri  = 'file://' . realpath('openapi.json'); // базовый URI документа
$document = $parser->parse($raw, $profile, $options, $baseUri);
// $document — экземпляр On1kel\OAS\Model\OpenApiDocument

use On1kel\OAS\Serialize\DefaultSerializer;
use On1kel\OAS\Serialize\DefaultNormalizer;
use On1kel\OAS\Serialize\DefaultDenormalizer;
use On1kel\OAS\Serialize\TypeRegistry;

// Реестр фабрик типов для денормализации (если потребуется собирать модель «с нуля»)
$registry     = new TypeRegistry();
// $registry->register('OpenApiDocument', fn(array $data, $profile) => /* вернуть new OpenApiDocument(...) */);

$serializer   = new DefaultSerializer(
    normalizers: [new DefaultNormalizer()],   // можно добавить свои нормализаторы
    denormalizer: new DefaultDenormalizer($registry)
);

$array = $serializer->toArray($document, $profile);
$json  = $serializer->toJson($document, $profile, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);

// Обратные операции (если у вас есть массив/JSON и реалистичная регистрация типов в $registry):
// $doc2 = $serializer->fromArray($array, $profile);
// $doc3 = $serializer->fromJson($jsonString, $profile);

use On1kel\OAS\Traverse\Walker;
use On1kel\OAS\Contract\Traverse\NodeVisitor;

final class PrintVisitor implements NodeVisitor
{
    public function enter(string $pointer, object $node): void
    {
        echo "→ {$pointer} : " . get_class($node) . PHP_EOL;
    }

    public function leave(string $pointer, object $node): void {}
}

$walker = new Walker([new PrintVisitor()]);
$walker->walk($document); // Пройдётся по всем узлам, pointer — JSON Pointer узла

use On1kel\OAS\Validation\CompositeValidator;
use On1kel\OAS\Validation\Rule\UniqueOperationIdRule;
use On1kel\OAS\Validation\Rule\ReferenceNoSiblingsRule;
// ... другие правила в пространстве имён On1kel\OAS\Validation\Rule

$validator = new CompositeValidator([
    new UniqueOperationIdRule(),
    new ReferenceNoSiblingsRule(),
    // добавляйте нужные правила
]);

$violations = $validator->validate($document, $profile, $profile->strictness(), $baseUri);
foreach ($violations as $v) {
    // Объект/структура нарушения зависит от реализации правил; обработайте под свои нужды.
}

) Сырые данные
$raw = json_decode(file_get_contents('openapi.json'), true, 512, JSON_THROW_ON_ERROR);

// 2) Профиль и определение версии
$profiles = (new On1kel\OAS\Version\ProfileRegistry())
    ->register(new OAS31Profile());
$profile  = (new On1kel\OAS\Version\VersionDetector($profiles))->detect($raw);

// 3) Парсинг с $ref
$http    = /* PSR-18 клиент */;
$reqFac  = /* PSR-17 RequestFactory */;
$strFac  = /* PSR-17 StreamFactory */;
$parser  = new On1kel\OAS\Parsing\DocumentParser(
    new On1kel\OAS\Ref\RefResolver(
        new On1kel\OAS\Ref\DefaultRefFetcher($http, $reqFac, $strFac)
    )
);
$opts    = (new On1kel\OAS\Version\ParseOptions())
    ->withResolveExternalRefs(true)
    ->withMaxRefDepth(64);
$baseUri = 'file://' . realpath('openapi.json');

$doc = $parser->parse($raw, $profile, $opts, $baseUri);

// 4) Сериализация и обход
$serializer = new On1kel\OAS\Serialize\DefaultSerializer([new On1kel\OAS\Serialize\DefaultNormalizer()], new On1kel\OAS\Serialize\DefaultDenormalizer(new On1kel\OAS\Serialize\TypeRegistry()));
echo $serializer->toJson($doc, $profile, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), PHP_EOL;

$walker = new On1kel\OAS\Traverse\Walker([new class implements On1kel\OAS\Contract\Traverse\NodeVisitor {
    public function enter(string $p, object $n): void { echo $p, PHP_EOL; }
    public function leave(string $p, object $n): void {}
}]);
$walker->walk($doc);