#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",
+    "ronasit/laravel-helpers": "~2.1.0"
   },
   "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. Title and version fields are required.
         */
         'description' => 'auto-doc::swagger-description',
         'version' => '0.0.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("Validation failed. 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("Validation failed. 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("Validation failed. Path '{$path}' has multiple path placeholders with name: {$placeholdersString}.");
+    }
+}

src/Exceptions/SpecValidation/InvalidFieldValueException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+class InvalidFieldValueException extends InvalidSwaggerSpecException
+{
+    public function __construct(string $fieldId, array $allowedValues)
+    {
+        $allowedValuesString = implode(', ', $allowedValues);
+
+        parent::__construct("Validation failed. Field '{$fieldId}' has an invalid value. 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("Validation failed at '{$path}'. Paths should only have path names that starts with `/`.");
+    }
+}

src/Exceptions/SpecValidation/InvalidStatusCodeException.php

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

src/Exceptions/SpecValidation/InvalidSwaggerSpecException.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace RonasIT\Support\AutoDoc\Exceptions\SpecValidation;
+
+use Exception;
+
+class InvalidSwaggerSpecException extends Exception
+{
+}

src/Exceptions/SpecValidation/InvalidSwaggerVersionException.php

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

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("Validation failed. 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("Validation failed. '{$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("Validation failed. 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("Validation failed. 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("Validation failed. 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("Validation failed. Filename '{$filename}' is used in \$ref but file doesn't exist.");
+    }
+}

src/Services/SwaggerService.php

@@ -10,10 +10,13 @@
 use ReflectionClass;
 use RonasIT\Support\AutoDoc\Exceptions\InvalidDriverClassException;
 use RonasIT\Support\AutoDoc\Exceptions\LegacyConfigException;
+use RonasIT\Support\AutoDoc\Exceptions\SpecValidation\InvalidSwaggerSpecException;
+use RonasIT\Support\AutoDoc\Exceptions\SpecValidation\InvalidSwaggerVersionException;
 use RonasIT\Support\AutoDoc\Exceptions\SwaggerDriverClassNotFoundException;
 use RonasIT\Support\AutoDoc\Exceptions\WrongSecurityConfigException;
 use RonasIT\Support\AutoDoc\Interfaces\SwaggerDriverInterface;
 use RonasIT\Support\AutoDoc\Traits\GetDependenciesTrait;
+use RonasIT\Support\AutoDoc\Validators\SwaggerSpecValidator;
 use Symfony\Component\HttpFoundation\Response;
 
 /**
@@ -61,7 +64,9 @@ public function __construct(Container $container)
 
             $this->data = $this->driver->getTmpData();
 
-            if (empty($this->data)) {
+            if (!empty($this->data)) {
+                $this->validateSpec($this->data);
+            } else {
                 $this->data = $this->generateEmptyData();
 
                 $this->driver->saveTmpData($this->data);
@@ -84,6 +89,10 @@ protected function initConfig()
         if (version_compare($packageConfigs['config_version'], $version, '>')) {
             throw new LegacyConfigException();
         }
+
+        if (version_compare($this->config['swagger']['version'], '2.0', '!=')) {
+            throw new InvalidSwaggerVersionException($this->config['swagger']['version']);
+        }
     }
 
     protected function setDriver()
@@ -105,49 +114,38 @@ protected function setDriver()
     protected function generateEmptyData(): array
     {
         $data = [
-            'swagger' => Arr::get($this->config, 'swagger.version'),
+            'swagger' => Arr::get($this->config, 'swagger.version', '2.0'),
             'host' => $this->getAppUrl(),
             'basePath' => $this->config['basePath'],
             'schemes' => $this->config['schemes'],
             'paths' => [],
-            'definitions' => $this->config['definitions']
+            'definitions' => $this->config['definitions'],
+            'info' => $this->prepareInfo($this->config['info'])
         ];
 
-        $info = $this->prepareInfo($this->config['info']);
-
-        if (!empty($info)) {
-            $data['info'] = $info;
-        }
-
         $securityDefinitions = $this->generateSecurityDefinition();
 
         if (!empty($securityDefinitions)) {
             $data['securityDefinitions'] = $securityDefinitions;
         }
 
-        if (!empty($data['info']['description'])) {
-            $data['info']['description'] = view($data['info']['description'])->render();
-        }
-
         return $data;
     }
 
-    protected function getAppUrl()
+    protected function getAppUrl(): string
     {
         $url = config('app.url');
 
         return str_replace(['http://', 'https://', '/'], '', $url);
     }
 
-    protected function generateSecurityDefinition()
+    protected function generateSecurityDefinition(): ?array
     {
-        if (empty($this->security)) {
-            return '';
-        }
-
-        return [
-            $this->security => $this->generateSecurityDefinitionObject($this->security)
-        ];
+        return (empty($this->security))
+            ? null
+            : [
+                $this->security => $this->generateSecurityDefinitionObject($this->security)
+            ];
     }
 
     protected function generateSecurityDefinitionObject($type): array
@@ -653,30 +651,40 @@ public function getDocFileContent()
             if (file_exists($fullFilePath)) {
                 $fileContent = json_decode(file_get_contents($fullFilePath), true);
 
-                $paths = array_keys($fileContent['paths']);
+                if ($fileContent) {
+                    try {
+                        $this->validateSpec($fileContent);
+                    } catch (InvalidSwaggerSpecException $exception) {
+                        report($exception);
+
+                        continue;
+                    }
+
+                    $paths = array_keys($fileContent['paths']);
 
-                foreach ($paths as $path) {
-                    $additionalDocPath = $fileContent['paths'][$path];
+                    foreach ($paths as $path) {
+                        $additionalDocPath = $fileContent['paths'][$path];
 
-                    if (empty($documentation['paths'][$path])) {
-                        $documentation['paths'][$path] = $additionalDocPath;
-                    } else {
-                        $methods = array_keys($documentation['paths'][$path]);
-                        $additionalDocMethods = array_keys($additionalDocPath);
+                        if (empty($documentation['paths'][$path])) {
+                            $documentation['paths'][$path] = $additionalDocPath;
+                        } else {
+                            $methods = array_keys($documentation['paths'][$path]);
+                            $additionalDocMethods = array_keys($additionalDocPath);
 
-                        foreach ($additionalDocMethods as $method) {
-                            if (!in_array($method, $methods)) {
-                                $documentation['paths'][$path][$method] = $additionalDocPath[$method];
+                            foreach ($additionalDocMethods as $method) {
+                                if (!in_array($method, $methods)) {
+                                    $documentation['paths'][$path][$method] = $additionalDocPath[$method];
+                                }
                             }
                         }
                     }
-                }
 
-                $definitions = array_keys($fileContent['definitions']);
+                    $definitions = array_keys($fileContent['definitions']);
 
-                foreach ($definitions as $definition) {
-                    if (empty($documentation['definitions'][$definition])) {
-                        $documentation['definitions'][$definition] = $fileContent['definitions'][$definition];
+                    foreach ($definitions as $definition) {
+                        if (empty($documentation['definitions'][$definition])) {
+                            $documentation['definitions'][$definition] = $fileContent['definitions'][$definition];
+                        }
                     }
                 }
             }
@@ -787,25 +795,29 @@ protected function getDefaultValueByType($type)
         return $values[$type];
     }
 
-    /**
-     * @param $info
-     * @return mixed
-     */
-    protected function prepareInfo($info)
+    protected function prepareInfo(array $info): array
     {
-        if (empty($info)) {
-            return $info;
-        }
-
         foreach ($info['license'] as $key => $value) {
             if (empty($value)) {
                 unset($info['license'][$key]);
             }
         }
+
         if (empty($info['license'])) {
             unset($info['license']);
         }
 
+        if (!empty($info['description'])) {
+            $info['description'] = view($info['description'])->render();
+        }
+
         return $info;
     }
+
+    protected function validateSpec(array $doc): void
+    {
+        $validator = new SwaggerSpecValidator($doc);
+
+        $validator->validate();
+    }
 }