BookStack/app/Api/ApiDocsGenerator.php

192 lines
6.3 KiB
PHP
Raw Normal View History

2021-06-26 17:23:15 +02:00
<?php
namespace BookStack\Api;
2020-01-12 17:25:14 +01:00
use BookStack\Http\ApiController;
use Exception;
use Illuminate\Contracts\Container\BindingResolutionException;
2020-01-12 17:25:14 +01:00
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;
2020-01-12 17:25:14 +01:00
use Illuminate\Support\Facades\Route;
2020-04-10 17:05:17 +02:00
use Illuminate\Support\Str;
use Illuminate\Validation\Rules\Password;
2020-01-12 17:25:14 +01:00
use ReflectionClass;
use ReflectionException;
use ReflectionMethod;
class ApiDocsGenerator
{
protected array $reflectionClasses = [];
protected array $controllerClasses = [];
2020-01-12 17:25:14 +01:00
/**
* Load the docs form the cache if existing
* otherwise generate and store in the cache.
*/
public static function generateConsideringCache(): Collection
{
$appVersion = trim(file_get_contents(base_path('version')));
$cacheKey = 'api-docs::' . $appVersion;
$isProduction = config('app.env') === 'production';
$cacheVal = $isProduction ? Cache::get($cacheKey) : null;
if (!is_null($cacheVal)) {
return $cacheVal;
}
2021-06-26 17:23:15 +02:00
$docs = (new ApiDocsGenerator())->generate();
Cache::put($cacheKey, $docs, 60 * 24);
return $docs;
}
2020-01-12 17:25:14 +01:00
/**
* Generate API documentation.
*/
protected function generate(): Collection
2020-01-12 17:25:14 +01:00
{
$apiRoutes = $this->getFlatApiRoutes();
$apiRoutes = $this->loadDetailsFromControllers($apiRoutes);
$apiRoutes = $this->loadDetailsFromFiles($apiRoutes);
$apiRoutes = $apiRoutes->groupBy('base_model');
2021-06-26 17:23:15 +02:00
2020-01-12 17:25:14 +01:00
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;
}
2021-06-26 17:23:15 +02:00
2020-01-12 17:25:14 +01:00
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) {
$method = $this->getReflectionMethod($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']);
2021-06-26 17:23:15 +02:00
2020-01-12 17:25:14 +01:00
return $route;
});
}
/**
* Load body params and their rules by inspecting the given class and method name.
2021-06-26 17:23:15 +02:00
*
* @throws BindingResolutionException
2020-01-12 17:25:14 +01:00
*/
protected function getBodyParamsFromClass(string $className, string $methodName): ?array
{
/** @var ApiController $class */
$class = $this->controllerClasses[$className] ?? null;
if ($class === null) {
$class = app()->make($className);
$this->controllerClasses[$className] = $class;
}
2022-02-08 16:29:58 +01:00
$rules = collect($class->getValidationRules()[$methodName] ?? [])->map(function ($validations) {
return array_map(function ($validation) {
return $this->getValidationAsString($validation);
}, $validations);
})->toArray();
2021-11-05 01:28:41 +01:00
return empty($rules) ? null : $rules;
2020-01-12 17:25:14 +01:00
}
/**
* 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);
2022-02-08 16:29:58 +01:00
throw new Exception("Cannot provide string representation of rule for class: {$class}");
}
2020-01-12 17:25:14 +01:00
/**
* Parse out the description text from a class method comment.
*/
protected function parseDescriptionFromMethodComment(string $comment): string
2020-01-12 17:25:14 +01:00
{
$matches = [];
preg_match_all('/^\s*?\*\s?($|((?![\/@\s]).*?))$/m', $comment, $matches);
2021-06-26 17:23:15 +02:00
$text = implode(' ', $matches[1] ?? []);
return str_replace(' ', "\n", $text);
2020-01-12 17:25:14 +01:00
}
/**
* Get a reflection method from the given class name and method name.
2021-06-26 17:23:15 +02:00
*
2020-01-12 17:25:14 +01:00
* @throws ReflectionException
*/
protected function getReflectionMethod(string $className, string $methodName): ReflectionMethod
{
$class = $this->reflectionClasses[$className] ?? null;
if ($class === null) {
$class = new ReflectionClass($className);
$this->reflectionClasses[$className] = $class;
}
return $class->getMethod($methodName);
}
/**
* Get the system API routes, formatted into a flat collection.
*/
protected function getFlatApiRoutes(): Collection
{
return collect(Route::getRoutes()->getRoutes())->filter(function ($route) {
return strpos($route->uri, 'api/') === 0;
})->map(function ($route) {
[$controller, $controllerMethod] = explode('@', $route->action['uses']);
2020-01-15 21:18:02 +01:00
$baseModelName = explode('.', explode('/', $route->uri)[1])[0];
2020-01-12 17:25:14 +01:00
$shortName = $baseModelName . '-' . $controllerMethod;
2021-06-26 17:23:15 +02:00
2020-01-12 17:25:14 +01:00
return [
2021-06-26 17:23:15 +02:00
'name' => $shortName,
'uri' => $route->uri,
'method' => $route->methods[0],
'controller' => $controller,
'controller_method' => $controllerMethod,
2020-04-10 17:05:17 +02:00
'controller_method_kebab' => Str::kebab($controllerMethod),
2021-06-26 17:23:15 +02:00
'base_model' => $baseModelName,
2020-01-12 17:25:14 +01:00
];
});
}
2021-03-07 23:24:05 +01:00
}