#45: Add swagger spec validator to validate temp and additional doc format

composer.json

@@ -18,7 +18,8 @@
   "require": {
     "php": ">=7.3.0",
     "laravel/framework": ">=5.3.0",
-    "phpunit/phpunit": ">=7.0"
+    "phpunit/phpunit": ">=7.0",
+    "ext-json": "*"
   },
   "require-dev": {
     "orchestra/testbench": "^6.25",

config/auto-doc.php

@@ -40,7 +40,7 @@
         | Documentation Template
         |--------------------------------------------------------------------------
         |
-        | You can use your custom documentation view
+        | You can use your custom documentation view.
         */
         'description' => 'auto-doc::swagger-description',
         'version' => '0.0.0',
@@ -54,9 +54,6 @@
             'url' => ''
         ]
     ],
-    'swagger' => [
-        'version' => '2.0'
-    ],
 
     /*
     |--------------------------------------------------------------------------

src/Exceptions/SpecValidation/DuplicateFieldException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class DuplicateFieldException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $fieldName, array $fieldValue)
+    {
+        $fieldValueString = implode(', ', $fieldValue);
+
+        parent::__construct("Found multiple fields '{$fieldName}' with values: {$fieldValueString}.");
+    }
+}

src/Exceptions/SpecValidation/DuplicateParamException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class DuplicateParamException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $in, string $name, string $operationId)
+    {
+        parent::__construct("Operation '{$operationId}' has multiple in:{$in} parameters with name:{$name}.");
+    }
+}

src/Exceptions/SpecValidation/DuplicatePathPlaceholderException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class DuplicatePathPlaceholderException extends InvalidSwaggerSpecException
+{
+    public function __construct(array $placeholders, string $path)
+    {
+        $placeholdersString = implode(', ', $placeholders);
+
+        parent::__construct("Path '{$path}' has multiple path placeholders with name: {$placeholdersString}.");
+    }
+}

src/Exceptions/SpecValidation/InvalidFieldValueException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class InvalidFieldValueException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $fieldName, array $allowedValues, array $invalidValues)
+    {
+        $allowedValuesString = implode(', ', $allowedValues);
+        $invalidValuesString = implode(', ', $invalidValues);
+
+        parent::__construct(
+            "Field '{$fieldName}' has an invalid value: {$invalidValuesString}. Allowed values: {$allowedValuesString}."
+        );
+    }
+}

src/Exceptions/SpecValidation/InvalidPathException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class InvalidPathException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $path)
+    {
+        parent::__construct("Incorrect '{$path}'. Paths should only have path names that starts with `/`.");
+    }
+}

src/Exceptions/SpecValidation/InvalidStatusCodeException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class InvalidStatusCodeException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $responseId)
+    {
+        parent::__construct(
+            "Operation at '{$responseId}' should only have three-digit status codes, `default`, "
+            . "and vendor extensions (`x-*`) as properties."
+        );
+    }
+}

src/Exceptions/SpecValidation/InvalidSwaggerSpecException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+use Exception;
+
+class InvalidSwaggerSpecException extends Exception
+{
+    public function __construct($message = '')
+    {
+        parent::__construct('Validation failed. '. $message);
+    }
+}

src/Exceptions/SpecValidation/InvalidSwaggerVersionException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+use RonasIT\Support\AutoDoc\Services\SwaggerService;
+
+class InvalidSwaggerVersionException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $version)
+    {
+        $expectedVersion = SwaggerService::SWAGGER_VERSION;
+
+        parent::__construct("Unrecognized Swagger version '{$version}'. Expected {$expectedVersion}.");
+    }
+}

src/Exceptions/SpecValidation/MissingExternalRefException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class MissingExternalRefException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $ref, string $filename)
+    {
+        parent::__construct("Ref '{$ref}' is used in \$ref but not defined in '{$filename}' file.");
+    }
+}

src/Exceptions/SpecValidation/MissingFieldException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class MissingFieldException extends InvalidSwaggerSpecException
+{
+    public function __construct(array $missingFields, string $parentField = null)
+    {
+        $fieldsString = implode(', ', $missingFields);
+
+        parent::__construct("'{$parentField}' should have required fields: {$fieldsString}.");
+    }
+}

src/Exceptions/SpecValidation/MissingLocalRefException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class MissingLocalRefException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $ref, string $parentField)
+    {
+        parent::__construct("Ref '{$ref}' is used in \$ref but not defined in '{$parentField}' field.");
+    }
+}

src/Exceptions/SpecValidation/MissingPathParamException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class MissingPathParamException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $operationId, array $placeholders)
+    {
+        $placeholdersString = implode(', ', $placeholders);
+
+        parent::__construct("Operation '{$operationId}' has no params for placeholders: {$placeholdersString}.");
+    }
+}

src/Exceptions/SpecValidation/MissingPathPlaceholderException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class MissingPathPlaceholderException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $operationId, array $params)
+    {
+        $paramsString = implode(', ', $params);
+
+        parent::__construct("Operation '{$operationId}' has no placeholders for params: {$paramsString}.");
+    }
+}

src/Exceptions/SpecValidation/MissingRefFileException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class MissingRefFileException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $filename)
+    {
+        parent::__construct("Filename '{$filename}' is used in \$ref but file doesn't exist.");
+    }
+}