ApiDocsGenerator.php

<?php

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\Facades\Cache;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Str;
use Illuminate\Validation\Rules\Password;
use ReflectionClass;
use ReflectionException;
use ReflectionMethod;

class ApiDocsGenerator
{
    /**
     * @var array<string, ReflectionClass>
     */
    protected array $reflectionClasses = [];

    /**
     * @var array<string, ApiController>
     */
    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;
        }

        $docs = (new ApiDocsGenerator())->generate();
        Cache::put($cacheKey, $docs, 60 * 24);

        return $docs;
    }

    /**
     * Generate API documentation.
     */
    protected function generate(): Collection
    {
        $apiRoutes = $this->getFlatApiRoutes();
        $apiRoutes = $this->loadDetailsFromControllers($apiRoutes);
        $apiRoutes = $this->loadDetailsFromFiles($apiRoutes);
        $apiRoutes = $apiRoutes->groupBy('base_model');

        return $apiRoutes;
    }

    /**
     * Load any API details stored in static files.
     */
    protected function loadDetailsFromFiles(Collection $routes): Collection
    {
        return $routes->map(function (array $route) {
            $exampleTypes = ['request', 'response'];
            $fileTypes = ['json', 'http'];
            foreach ($exampleTypes as $exampleType) {
                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;
        });
    }

    /**
     * Load any details we can fetch from the controller and its methods.
     */
    protected function loadDetailsFromControllers(Collection $routes): Collection
    {
        return $routes->map(function (array $route) {
            $class = $this->getReflectionClass($route['controller']);
            $method = $this->getReflectionMethod($route['controller'], $route['controller_method']);
            $comment = $method->getDocComment();
            $route['description'] = $comment ? $this->parseDescriptionFromDocBlockComment($comment) : null;
            $route['body_params'] = $this->getBodyParamsFromClass($route['controller'], $route['controller_method']);

            // Load class description for the model
            // Not ideal to have it here on each route, but adding it in a more structured manner would break
            // docs resulting JSON format and therefore be an API break.
            // Save refactoring for a more significant set of changes.
            $classComment = $class->getDocComment();
            $route['model_description'] = $classComment ? $this->parseDescriptionFromDocBlockComment($classComment) : null;

            return $route;
        });
    }

    /**
     * Load body params and their rules by inspecting the given class and method name.
     *
     * @throws BindingResolutionException
     */
    protected function getBodyParamsFromClass(string $className, string $methodName): ?array
    {
        $class = $this->controllerClasses[$className] ?? null;
        if ($class === null) {
            $class = app()->make($className);
            $this->controllerClasses[$className] = $class;
        }

        $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;
        }

        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.
     */
    protected function parseDescriptionFromDocBlockComment(string $comment): string
    {
        $matches = [];
        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.
     *
     * @throws ReflectionException
     */
    protected function getReflectionMethod(string $className, string $methodName): ReflectionMethod
    {
        return $this->getReflectionClass($className)->getMethod($methodName);
    }

    /**
     * Get a reflection class from the given class name.
     *
     * @throws ReflectionException
     */
    protected function getReflectionClass(string $className): ReflectionClass
    {
        $class = $this->reflectionClasses[$className] ?? null;
        if ($class === null) {
            $class = new ReflectionClass($className);
            $this->reflectionClasses[$className] = $class;
        }

        return $class;
    }

    /**
     * Get the system API routes, formatted into a flat collection.
     */
    protected function getFlatApiRoutes(): Collection
    {
        return collect(Route::getRoutes()->getRoutes())->filter(function ($route) {
            return str_starts_with($route->uri, 'api/');
        })->map(function ($route) {
            [$controller, $controllerMethod] = explode('@', $route->action['uses']);
            $baseModelName = explode('.', explode('/', $route->uri)[1])[0];
            $controllerMethodKebab = Str::kebab($controllerMethod);
            $shortName = $baseModelName . '-' . $controllerMethodKebab;

            return [
                'name'                    => $shortName,
                'uri'                     => $route->uri,
                'method'                  => $route->methods[0],
                'controller'              => $controller,
                'controller_method'       => $controllerMethod,
                'controller_method_kebab' => $controllerMethodKebab,
                'base_model'              => $baseModelName,
            ];
        });
    }
}