ZIP Imports: Added API examples, finished testing

[bookstack] / app / Api / ApiDocsGenerator.php

diff --git a/app/Api/ApiDocsGenerator.php b/app/Api/ApiDocsGenerator.php
index ddba24bdb65d6ec8dc1474e3d50996c546623228..287c838779060b9e23fa600f61e758d862649658 100644 (file)
--- a/app/Api/ApiDocsGenerator.php
+++ b/app/Api/ApiDocsGenerator.php
@@ -1,28 +1,56 @@
-<?php namespace BookStack\Api;
+<?php

 
 

-use BookStack\Http\Controllers\Api\ApiController;
+namespace BookStack\Api;
+
+use BookStack\App\AppVersion;
+use BookStack\Http\ApiController;
+use Exception;
+use Illuminate\Contracts\Container\BindingResolutionException;

 use Illuminate\Support\Collection;
 use Illuminate\Support\Collection;

+use Illuminate\Support\Facades\Cache;

 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\Str;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\Str;

+use Illuminate\Validation\Rules\Password;

 use ReflectionClass;
 use ReflectionException;
 use ReflectionMethod;
 
 class ApiDocsGenerator
 {
 use ReflectionClass;
 use ReflectionException;
 use ReflectionMethod;
 
 class ApiDocsGenerator
 {

+    protected array $reflectionClasses = [];
+    protected array $controllerClasses = [];
+
+    /**
+     * Load the docs form the cache if existing
+     * otherwise generate and store in the cache.
+     */
+    public static function generateConsideringCache(): Collection
+    {
+        $appVersion = AppVersion::get();
+        $cacheKey = 'api-docs::' . $appVersion;
+        $isProduction = config('app.env') === 'production';
+        $cacheVal = $isProduction ? Cache::get($cacheKey) : null;
+
+        if (!is_null($cacheVal)) {
+            return $cacheVal;
+        }

 
 

-    protected $reflectionClasses = [];
-    protected $controllerClasses = [];
+        $docs = (new ApiDocsGenerator())->generate();
+        Cache::put($cacheKey, $docs, 60 * 24);
+
+        return $docs;
+    }

 
     /**
      * Generate API documentation.
      */
 
     /**
      * Generate API documentation.
      */

-    public function generate(): Collection
+    protected function generate(): Collection

     {
         $apiRoutes = $this->getFlatApiRoutes();
         $apiRoutes = $this->loadDetailsFromControllers($apiRoutes);
         $apiRoutes = $this->loadDetailsFromFiles($apiRoutes);
         $apiRoutes = $apiRoutes->groupBy('base_model');
     {
         $apiRoutes = $this->getFlatApiRoutes();
         $apiRoutes = $this->loadDetailsFromControllers($apiRoutes);
         $apiRoutes = $this->loadDetailsFromFiles($apiRoutes);
         $apiRoutes = $apiRoutes->groupBy('base_model');

+

         return $apiRoutes;
     }
 
         return $apiRoutes;
     }
 


@@ -33,11 +61,18 @@ class ApiDocsGenerator
     {
         return $routes->map(function (array $route) {
             $exampleTypes = ['request', 'response'];
     {
         return $routes->map(function (array $route) {
             $exampleTypes = ['request', 'response'];

+            $fileTypes = ['json', 'http'];

             foreach ($exampleTypes as $exampleType) {
             foreach ($exampleTypes as $exampleType) {

-                $exampleFile = base_path("dev/api/{$exampleType}s/{$route['name']}.json");
-                $exampleContent = file_exists($exampleFile) ? file_get_contents($exampleFile) : null;
-                $route["example_{$exampleType}"] = $exampleContent;
+                foreach ($fileTypes as $fileType) {
+                    $exampleFile = base_path("dev/api/{$exampleType}s/{$route['name']}." . $fileType);
+                    if (file_exists($exampleFile)) {
+                        $route["example_{$exampleType}"] = file_get_contents($exampleFile);
+                        continue 2;
+                    }
+                }
+                $route["example_{$exampleType}"] = null;

             }
             }

+

             return $route;
         });
     }
             return $route;
         });
     }


@@ -52,13 +87,15 @@ class ApiDocsGenerator
             $comment = $method->getDocComment();
             $route['description'] = $comment ? $this->parseDescriptionFromMethodComment($comment) : null;
             $route['body_params'] = $this->getBodyParamsFromClass($route['controller'], $route['controller_method']);
             $comment = $method->getDocComment();
             $route['description'] = $comment ? $this->parseDescriptionFromMethodComment($comment) : null;
             $route['body_params'] = $this->getBodyParamsFromClass($route['controller'], $route['controller_method']);

+

             return $route;
         });
     }
 
     /**
      * Load body params and their rules by inspecting the given class and method name.
             return $route;
         });
     }
 
     /**
      * Load body params and their rules by inspecting the given class and method name.

-     * @throws \Illuminate\Contracts\Container\BindingResolutionException
+     *
+     * @throws BindingResolutionException

      */
     protected function getBodyParamsFromClass(string $className, string $methodName): ?array
     {
      */
     protected function getBodyParamsFromClass(string $className, string $methodName): ?array
     {


@@ -69,25 +106,52 @@ class ApiDocsGenerator
             $this->controllerClasses[$className] = $class;
         }
 
             $this->controllerClasses[$className] = $class;
         }
 

-        $rules = $class->getValdationRules()[$methodName] ?? [];
-        foreach ($rules as $param => $ruleString) {
-            $rules[$param] = explode('|', $ruleString);
+        $rules = collect($class->getValidationRules()[$methodName] ?? [])->map(function ($validations) {
+            return array_map(function ($validation) {
+                return $this->getValidationAsString($validation);
+            }, $validations);
+        })->toArray();
+
+        return empty($rules) ? null : $rules;
+    }
+
+    /**
+     * Convert the given validation message to a readable string.
+     */
+    protected function getValidationAsString($validation): string
+    {
+        if (is_string($validation)) {
+            return $validation;

         }
         }

-        return count($rules) > 0 ? $rules : null;
+
+        if (is_object($validation) && method_exists($validation, '__toString')) {
+            return strval($validation);
+        }
+
+        if ($validation instanceof Password) {
+            return 'min:8';
+        }
+
+        $class = get_class($validation);
+
+        throw new Exception("Cannot provide string representation of rule for class: {$class}");

     }
 
     /**
      * Parse out the description text from a class method comment.
      */
     }
 
     /**
      * Parse out the description text from a class method comment.
      */

-    protected function parseDescriptionFromMethodComment(string $comment)
+    protected function parseDescriptionFromMethodComment(string $comment): string

     {
         $matches = [];
     {
         $matches = [];

-        preg_match_all('/^\s*?\*\s((?![@\s]).*?)$/m', $comment, $matches);
-        return implode(' ', $matches[1] ?? []);
+        preg_match_all('/^\s*?\*\s?($|((?![\/@\s]).*?))$/m', $comment, $matches);
+
+        $text = implode(' ', $matches[1] ?? []);
+        return str_replace('  ', "\n", $text);

     }
 
     /**
      * Get a reflection method from the given class name and method name.
     }
 
     /**
      * Get a reflection method from the given class name and method name.

+     *

      * @throws ReflectionException
      */
     protected function getReflectionMethod(string $className, string $methodName): ReflectionMethod
      * @throws ReflectionException
      */
     protected function getReflectionMethod(string $className, string $methodName): ReflectionMethod


@@ -112,16 +176,16 @@ class ApiDocsGenerator
             [$controller, $controllerMethod] = explode('@', $route->action['uses']);
             $baseModelName = explode('.', explode('/', $route->uri)[1])[0];
             $shortName = $baseModelName . '-' . $controllerMethod;
             [$controller, $controllerMethod] = explode('@', $route->action['uses']);
             $baseModelName = explode('.', explode('/', $route->uri)[1])[0];
             $shortName = $baseModelName . '-' . $controllerMethod;

+

             return [
             return [

-                'name' => $shortName,
-                'uri' => $route->uri,
-                'method' => $route->methods[0],
-                'controller' => $controller,
-                'controller_method' => $controllerMethod,
+                'name'                    => $shortName,
+                'uri'                     => $route->uri,
+                'method'                  => $route->methods[0],
+                'controller'              => $controller,
+                'controller_method'       => $controllerMethod,

                 'controller_method_kebab' => Str::kebab($controllerMethod),
                 'controller_method_kebab' => Str::kebab($controllerMethod),

-                'base_model' => $baseModelName,
+                'base_model'              => $baseModelName,

             ];
         });
     }
             ];
         });
     }

-
-}
\ No newline at end of file
+}