Merge pull request #7 from membrane-php/own-api-objects

Validation with own API value objects

Author: carnage

composer.json

@@ -9,6 +9,7 @@
   },
   "autoload-dev": {
     "psr-4": {
+      "Membrane\\OpenAPIReader\\Tests\\Fixtures\\Helper\\": "tests/fixtures/Helper",
       "Membrane\\OpenAPIReader\\Tests\\Fixtures\\": "tests/fixtures/",
       "Membrane\\OpenAPIReader\\Tests\\": "tests/"
     }
@@ -19,7 +20,7 @@
   },
   "require-dev": {
     "phpunit/phpunit": "^10.1",
-    "phpstan/phpstan": "^1.10.19",
+    "phpstan/phpstan": "^1.10.56",
     "squizlabs/php_codesniffer": "^3.7",
     "mikey179/vfsstream": "^1.6.7",
     "infection/infection": "^0.27.0"

docs/validation.md

@@ -0,0 +1,58 @@
+# Validation Performed By OpenAPI Reader
+
+## Additional Requirements For Membrane.
+
+### Specify an OperationId
+
+Membrane requires all Operations to set a [unique](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-8) `operationId`.
+
+This is used for identification of all available operations across your OpenAPI.
+
+### Unambiguous Query Strings
+
+For query parameters (i.e. `in:query`)  with a `schema` that allows compound types i.e. `array` or `objects`
+there are certain combinations of `style` and `explode` that do not use the parameter's `name`.
+
+These combinations are:
+- `type:object` with `style:form` and `explode:true`
+- `type:object` or `type:array` with `style:spaceDelimited`
+- `type:object` or `type:array` with `style:pipeDelimited`
+
+If an operation only has one query parameter (i.e. `in:query`) then this is fine. Membrane can safely assume the entire string belongs to that one parameter.
+
+If an operation contains two query parameters, both of which do not use the parameter's name; Membrane cannot ascertain which parameter relates to which part of the query string.
+
+This ambiguity leads to multiple "correct" ways to interpret the query string. Making it impossible to safely assume Membrane has validated it. Therefore, only one parameter, with one of the above combinations, is allowed on any given Operation.
+
+## Version 3.0.X
+
+### OpenAPI Object
+
+- [An OpenAPI Object requires an `openapi` field](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields).
+- [An OpenAPI Object requires an `info` field](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields).
+  - [The Info Object requires a `title`](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-1).
+  - [The Info Object requires a `version`](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-1).
+- [All Path Items must be mapped to by their relative endpoint](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#paths-object).
+### Path Item
+
+- [All Operations MUST be mapped to by a method](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-7).
+- [Parameters must be unique. Uniqueness is defined by a combination of "name" and "in".](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-7)
+
+### Operation
+
+- [Parameters must be unique. Uniqueness is defined by a combination of "name" and "in".](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-8)
+
+### Parameter
+
+- A Parameter [MUST contain a `name` field](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-10).
+- A Parameter [MUST contain an `in` field](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-10).
+  - `in` [MUST be set to `path`, `query`, `header` or `cookie`](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-10).
+  - [if `in:path` then the Parameter MUST specify `required:true`](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-10).
+  - if `style` is specified, [acceptable values depend on the value of `in`](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#style-values). 
+- [A Parameter MUST contain a `schema` or `content`, but not both](https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.0.3.md#fixed-fields-10).
+  - if `content` is specified, it MUST contain exactly one Media Type
+    - A Parameter's MediaType MUST contain a schema.
+
+### Schema
+
+- [If allOf, anyOf or oneOf are set; They MUST not be empty](https://json-schema.org/draft/2020-12/json-schema-core#section-10.2).

infection.json5

@@ -3,11 +3,14 @@
     "source": {
         "directories": [
             "src"
+        ],
+        "excludes": [
+            "Exception", // We don't need the Exception messages being altered
         ]
     },
-    minCoveredMsi: 90,
-    minMsi: 80,
+    "minCoveredMsi": 90,
+    "minMsi": 80,
     "mutators": {
-        "@default": true,
-    },
+        "@default": true
+    }
 }

src/CebeReader.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Membrane\OpenAPIReader;
+
+use cebe\{openapi as Cebe, openapi\exceptions as CebeException, openapi\spec as CebeSpec};
+use Closure;
+use Membrane\OpenAPIReader\Exception\{CannotRead, CannotSupport, InvalidOpenAPI};
+use Membrane\OpenAPIReader\Factory\V30\FromCebe;
+use Symfony\Component\Yaml\Exception\ParseException;
+use TypeError;
+
+class CebeReader
+{
+    /** @param OpenAPIVersion[] $supportedVersions */
+    public function __construct(
+        private readonly array $supportedVersions,
+    ) {
+        if (empty($this->supportedVersions)) {
+            throw CannotSupport::noSupportedVersions();
+        }
+        (fn (OpenAPIVersion ...$versions) => null)(...$this->supportedVersions);
+    }
+
+    public function readFromAbsoluteFilePath(string $absoluteFilePath, ?FileFormat $fileFormat = null): CebeSpec\OpenApi
+    {
+        file_exists($absoluteFilePath) ?: throw CannotRead::fileNotFound($absoluteFilePath);
+
+        $fileFormat ??= FileFormat::fromFileExtension(pathinfo($absoluteFilePath, PATHINFO_EXTENSION));
+
+        try {
+            $openAPI = $this->getCebeObject(match ($fileFormat) {
+                FileFormat::Json => fn() => Cebe\Reader::readFromJsonFile($absoluteFilePath),
+                FileFormat::Yaml => fn() => Cebe\Reader::readFromYamlFile($absoluteFilePath),
+                default => throw CannotRead::unrecognizedFileFormat($absoluteFilePath)
+            });
+        } catch (CebeException\UnresolvableReferenceException $e) {
+            throw CannotRead::unresolvedReference($e);
+        }
+
+        $this->validate($openAPI);
+
+        return $openAPI;
+    }
+
+    public function readFromString(string $openAPI, FileFormat $fileFormat): CebeSpec\OpenApi
+    {
+        if (preg_match('#\s*[\'\"]?\$ref[\'\"]?\s*:\s*[\'\"]?[^\s\'\"\#]#', $openAPI)) {
+            throw CannotRead::cannotResolveExternalReferencesFromString();
+        }
+
+        $openAPI = $this->getCebeObject(match ($fileFormat) {
+            FileFormat::Json => fn() => Cebe\Reader::readFromJson($openAPI),
+            FileFormat::Yaml => fn() => Cebe\Reader::readFromYaml($openAPI),
+        });
+
+        try {
+            $openAPI->resolveReferences(new Cebe\ReferenceContext($openAPI, '/tmp'));
+        } catch (CebeException\UnresolvableReferenceException $e) {
+            throw CannotRead::unresolvedReference($e);
+        }
+
+        $this->validate($openAPI);
+
+        return $openAPI;
+    }
+
+    /** @param Closure():CebeSpec\OpenApi $readOpenAPI */
+    private function getCebeObject(Closure $readOpenAPI): CebeSpec\OpenApi
+    {
+        try {
+            return $readOpenAPI();
+        } catch (TypeError | CebeException\TypeErrorException | ParseException $e) {
+            throw CannotRead::invalidFormatting($e);
+        }
+    }
+
+    private function validate(CebeSpec\OpenApi $openAPI): void
+    {
+        $this->isVersionSupported($openAPI->openapi) ?: throw CannotSupport::unsupportedVersion($openAPI->openapi);
+
+        /** Currently only 3.0 Validated Objects exist */
+        if (OpenAPIVersion::fromString($openAPI->openapi) === OpenAPIVersion::Version_3_0) {
+            FromCebe::createOpenAPI($openAPI);
+        }
+
+        $openAPI->validate() ?: throw InvalidOpenAPI::failedCebeValidation(...$openAPI->getErrors());
+    }
+
+    private function isVersionSupported(string $version): bool
+    {
+        return in_array(OpenAPIVersion::fromString($version), $this->supportedVersions, true);
+    }
+}

src/Exception/CannotSupport.php

@@ -9,19 +9,19 @@
 /*
  * This exception occurs if your Open API is readable but cannot be supported by Membrane.
  */
+
 final class CannotSupport extends RuntimeException
 {
-    public const UNSUPPORTED_METHOD = 0;
-    public const UNSUPPORTED_VERSION = 1;
-    public const MISSING_OPERATION_ID = 2;
+    public const UNSUPPORTED_VERSION = 0;
+    public const MISSING_OPERATION_ID = 1;
+    public const MISSING_TYPE_DECLARATION = 2;
+    public const AMBIGUOUS_RESOLUTION = 3;
+    public const CANNOT_PARSE = 4;
 
-    public static function unsupportedMethod(string $pathUrl, string $method): self
+    public static function membraneReaderOnlySupportsv30(): self
     {
-        $message = <<<TEXT
-            Membrane does not currently support the method: '$method'.
-            Found on Path: '$pathUrl'
-            TEXT;
-        return new self($message, self::UNSUPPORTED_METHOD);
+        $message = 'MembraneReader currently only supports Version 3.0.X';
+        return new self($message, self::UNSUPPORTED_VERSION);
     }
 
     public static function noSupportedVersions(): self
@@ -46,4 +46,17 @@ public static function missingOperationId(string $pathUrl, string $method): self
             TEXT;
         return new self($message, self::MISSING_OPERATION_ID);
     }
+
+    public static function conflictingParameterStyles(string ...$parameters): self
+    {
+        $message = sprintf(
+            <<<'TEXT'
+            The following parameters lead to ambiguous resolution:
+            %s
+            TEXT,
+            implode(",\n", $parameters)
+        );
+
+        return new self($message, self::AMBIGUOUS_RESOLUTION);
+    }
 }