Support full dereferenced OpenAPI documents

src/Concerns/HasReferences.php

@@ -2,32 +2,40 @@
 
 namespace Apiboard\OpenAPI\Concerns;
 
-use Apiboard\OpenAPI\References\JsonReference;
+use Apiboard\OpenAPI\References\JsonPointer;
+use Apiboard\OpenAPI\References\Reference;
 
 trait HasReferences
 {
     abstract public function toArray(): array;
 
     /**
-     * @return array<JsonReference>
+     * @return array<array-key,Reference>
      */
     public function references(): array
     {
-        $properties = $this->toArray();
-
-        $references = [];
-
-        array_walk_recursive($properties, function (mixed $value, string $key) use (&$references) {
-            if ($value instanceof JsonReference) {
-                $references[] = $value;
+        $gatherReferences = function (array $data, JsonPointer $pointer, array $references = []) use (&$gatherReferences) {
+            foreach ($data as $property => $value) {
+                if ($property === '$ref') {
+                    $references[] = new Reference($value, $pointer);
+                    continue;
+                }
+
+                if ($this->isReference($value)) {
+                    $references[] = new Reference($value['$ref'], $pointer->append($property));
+
+                    continue;
+                }
+
+                if (is_array($value)) {
+                    $references = $gatherReferences($value, $pointer->append($property), $references);
+                }
             }
 
-            if ($key === '$ref') {
-                $references[] = new JsonReference($value);
-            }
-        });
+            return $references;
+        };
 
-        return $references;
+        return $gatherReferences($this->toArray(), $this->pointer ?? new JsonPointer(''));
     }
 
     private function isReference(mixed $value): bool

src/Contents/Contents.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Apiboard\OpenAPI\Contents;
+
+use Apiboard\OpenAPI\References\JsonPointer;
+use Apiboard\OpenAPI\References\JsonReference;
+
+final class Contents
+{
+    private mixed $value;
+
+    public function __construct(mixed $value)
+    {
+        $this->value = $value;
+    }
+
+    public function value(): mixed
+    {
+        return $this->value;
+    }
+
+    public function at(JsonPointer $pointer): self
+    {
+        $data = $this->castToArray();
+
+        foreach ($pointer->getPropertyPaths() as $property) {
+            $data = $data[$property];
+        }
+
+        return new self($data);
+    }
+
+    public function containsJsonReference(JsonReference $jsonReference): bool
+    {
+        $data = $this->castToArray();
+
+        if ($data === null) {
+            return false;
+        }
+
+        $containsReference = false;
+
+        array_walk_recursive($data, function (mixed $value, mixed $key) use (&$containsReference, $jsonReference) {
+            if ($containsReference) {
+                ;
+                return;
+            }
+
+            if ($key === '$ref') {
+                $containsReference = $value === $jsonReference->value();
+            }
+        });
+
+        return $containsReference;
+    }
+
+    public function isResolved(): bool
+    {
+        return match (gettype($this->value)) {
+            'string' => str_contains($this->value, '$ref'),
+            'array' => array_key_exists('$ref', $this->value),
+            'object' => array_key_exists('$ref', get_object_vars($this->value)),
+            default => true,
+        };
+    }
+
+    public function isJson(): bool
+    {
+        return (bool) json_decode($this->value);
+    }
+
+    public function isYaml(): bool
+    {
+        try {
+            return (bool) \Symfony\Component\Yaml\Yaml::parse($this->value);
+        } catch (\Symfony\Component\Yaml\Exception\ParseException $e) {
+            return false;
+        }
+    }
+
+    public function toString(): string
+    {
+        $data = $this->castToArray();
+
+        if ($data === null) {
+            return (string) $this->value;
+        }
+
+        if ($this->isJson()) {
+            return json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+        }
+
+        return \Symfony\Component\Yaml\Yaml::dump($data);
+    }
+
+    private function castToArray(): ?array
+    {
+        if (is_array($this->value)) {
+            return $this->value;
+        }
+
+        $array = json_decode($this->value, true, 512, JSON_UNESCAPED_SLASHES);
+
+        if ($array) {
+            return $array;
+        }
+
+        return null;
+    }
+}

src/Contents/Json.php

@@ -3,6 +3,7 @@
 namespace Apiboard\OpenAPI\Contents;
 
 use Apiboard\OpenAPI\Concerns\HasReferences;
+use Apiboard\OpenAPI\References\JsonPointer;
 
 final class Json
 {
@@ -26,7 +27,7 @@ public function toArray(): array
 
     public function toString(): string
     {
-        return json_encode($this->toObject(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+        return $this->toStringFromObject($this->toObject());
     }
 
     public function toObject(): object
@@ -36,6 +37,39 @@ public function toObject(): object
         return $this->castSpecificKeysToProperOASType($decoded);
     }
 
+    public function replaceAt(JsonPointer $pointer, Contents $replacement): self
+    {
+        $contents = $this->toObject();
+
+        $contentsAtPointer = &$contents;
+
+        foreach ($pointer->getPropertyPaths() as $property) {
+            $contentsAtPointer = &$contentsAtPointer->{$property};
+        }
+
+        $contentsAtPointer = $replacement->value();
+
+        return new self($this->toStringFromObject($contents));
+    }
+
+    public function at(JsonPointer $pointer): Contents
+    {
+        $contents = $this->toObject();
+
+        foreach ($pointer->getPropertyPaths() as $property) {
+            $contents = $contents->{$property};
+        }
+
+        return new Contents($contents);
+    }
+
+    private function toStringFromObject(object $object): string
+    {
+        $casted = $this->castSpecificKeysToProperOASType($object);
+
+        return json_encode($casted, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+    }
+
     private function castSpecificKeysToProperOASType(object $object): object
     {
         foreach ($object as $key => $value) {

src/Contents/Retriever.php

@@ -8,5 +8,5 @@ public function basePath(): string;
 
     public function from(string $basePath): Retriever;
 
-    public function retrieve(string $filePath): Json|Yaml;
+    public function retrieve(string $filePath): Contents;
 }

src/Contents/Retrievers/LocalFilesystemRetriever.php

@@ -2,9 +2,8 @@
 
 namespace Apiboard\OpenAPI\Contents\Retrievers;
 
-use Apiboard\OpenAPI\Contents\Json;
+use Apiboard\OpenAPI\Contents\Contents;
 use Apiboard\OpenAPI\Contents\Retriever;
-use Apiboard\OpenAPI\Contents\Yaml;
 use InvalidArgumentException;
 use Symfony\Component\Filesystem\Path;
 
@@ -19,23 +18,23 @@ public function basePath(): string
 
     public function from(string $basePath): Retriever
     {
-        $this->basePath = dirname($basePath).'/';
+        $this->basePath = dirname($basePath) . '/';
 
         return $this;
     }
 
-    public function retrieve(string $filePath): Json|Yaml
+    public function retrieve(string $filePath): Contents
     {
         $extension = pathinfo($filePath, PATHINFO_EXTENSION);
 
         if (str_starts_with($filePath, '/') === false) {
-            $filePath = Path::canonicalize($this->basePath.$filePath);
+            $filePath = Path::canonicalize($this->basePath . $filePath);
         }
 
-        return match ($extension) {
-            'json' => new Json(file_get_contents($filePath)),
-            'yaml' => new Yaml(file_get_contents($filePath)),
-            default => throw new InvalidArgumentException('Can only parse JSON or YAML files'),
-        };
+        if (in_array($extension, ['json', 'yaml'])) {
+            return new Contents(file_get_contents($filePath));
+        }
+
+        throw new InvalidArgumentException('Can only parse JSON or YAML files');
     }
 }

src/Contents/Yaml.php

@@ -3,6 +3,7 @@
 namespace Apiboard\OpenAPI\Contents;
 
 use Apiboard\OpenAPI\Concerns\HasReferences;
+use Apiboard\OpenAPI\References\JsonPointer;
 
 final class Yaml
 {
@@ -35,4 +36,30 @@ public function toObject(): object
 
         return (new Json($json))->toObject();
     }
+
+    public function replaceAt(JsonPointer $pointer, Contents $replacement): self
+    {
+        $contents = $this->toArray();
+
+        $contentsAtPointer = &$contents;
+
+        foreach ($pointer->getPropertyPaths() as $property) {
+            $contentsAtPointer = &$contentsAtPointer[$property];
+        }
+
+        $contentsAtPointer = $replacement->value();
+
+        return new self(\Symfony\Component\Yaml\Yaml::dump($contents));
+    }
+
+    public function at(JsonPointer $pointer): Contents
+    {
+        $contents = $this->toObject();
+
+        foreach ($pointer->getPropertyPaths() as $property) {
+            $contents = $contents->{$property};
+        }
+
+        return new Contents($contents);
+    }
 }

src/OpenAPI.php

@@ -2,6 +2,7 @@
 
 namespace Apiboard\OpenAPI;
 
+use Apiboard\OpenAPI\Contents\Contents;
 use Apiboard\OpenAPI\Contents\Json;
 use Apiboard\OpenAPI\Contents\Retriever;
 use Apiboard\OpenAPI\Contents\Retrievers\LocalFilesystemRetriever;
@@ -26,21 +27,21 @@ public function __construct(Retriever $retriever = null)
         $this->resolver = new Resolver($retriever);
         $this->validator = new \Opis\JsonSchema\Validator();
         $this->validator->resolver()
-            ->registerFile('https://apiboard.dev/oas-3.0.json', __DIR__.'/Validation/v3.0.json')
-            ->registerFile('https://apiboard.dev/oas-3.1.json', __DIR__.'/Validation/v3.1.json');
+            ->registerFile('https://apiboard.dev/oas-3.0.json', __DIR__ . '/Validation/v3.0.json')
+            ->registerFile('https://apiboard.dev/oas-3.1.json', __DIR__ . '/Validation/v3.1.json');
     }
 
     public function parse(string $filePath): Document
     {
-        $contents = $this->retriever->from($filePath)->retrieve($filePath);
+        $contents = $this->retrieve($filePath);
 
         $resolvedContents = $this->resolver->resolve($contents);
 
         $errorMessage = '';
 
         foreach ($this->validate($resolvedContents) as $pointer => $errors) {
             foreach ($errors as $error) {
-                $errorMessage .= "\n".$error." (~{$pointer})";
+                $errorMessage .= "\n" . $error . " (~{$pointer})";
             }
         }
 
@@ -53,7 +54,7 @@ public function parse(string $filePath): Document
 
     public function resolve(string $filePath): Json|Yaml
     {
-        $contents = $this->retriever->from($filePath)->retrieve($filePath);
+        $contents = $this->retrieve($filePath);
 
         return $this->resolver->resolve($contents);
     }
@@ -75,4 +76,15 @@ public function validate(Json|Yaml $contents): array
 
         return (new \Opis\JsonSchema\Errors\ErrorFormatter())->format($result->error());
     }
+
+    private function retrieve(string $filePath): Json|Yaml|Contents
+    {
+        $contents = $this->retriever->from($filePath)->retrieve($filePath);
+
+        return match (true) {
+            $contents->isJson() => new Json($contents->toString()),
+            $contents->isYaml() => new Yaml($contents->toString()),
+            default => $contents,
+        };
+    }
 }

src/References/JsonReference.php

@@ -47,8 +47,8 @@ public function isInternal(): bool
         return $this->path() === '';
     }
 
-    public function properties(): array
+    public function pointer(): JsonPointer
     {
-        return $this->pointer->getPropertyPaths();
+        return $this->pointer;
     }
 }