The API documentation was not properly generated for methods annotated with the subclassed RpcMethod.

This commit should be reverted as soon as this pull-request is accepted: sajya/server#87

Author: csavelief

app/Console/Commands/Docs.php

@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Routing\Route;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
+use Illuminate\Support\Stringable;
+use ReflectionClass;
+use ReflectionMethod;
+use Sajya\Server\Annotations\Param;
+use Sajya\Server\Attributes\RpcMethod;
+
+/** @deprecated Remove as soon as this pull-request is accepted : https://github.com/sajya/server/pull/87 */
+class Docs extends \Sajya\Server\Docs
+{
+    /**
+     * Docs constructor.
+     *
+     * @param Route $route
+     */
+    public function __construct(Route $route)
+    {
+        parent::__construct($route);
+    }
+
+    /**
+     * @return \Illuminate\Support\Collection
+     */
+    public function getAnnotations(): Collection
+    {
+        return collect($this->procedures)
+            ->map(function (string $class) {
+
+                $reflectionClass = new ReflectionClass($class);
+                $name = $reflectionClass->getProperty('name')->getValue();
+
+                return collect($reflectionClass->getMethods(ReflectionMethod::IS_PUBLIC))
+                    ->map(function (ReflectionMethod $method) use ($name) {
+
+                        $attributes = $this->getMethodAnnotations($method);
+
+                        $request = [
+                            'jsonrpc' => '2.0',
+                            'id' => 1,
+                            'method' => $name . $this->delimiter . $method->getName(),
+                            'params' => $attributes?->params,
+                        ];
+
+                        $response = [
+                            'jsonrpc' => '2.0',
+                            'id' => 1,
+                            'result' => $attributes?->result,
+                        ];
+
+                        return [
+                            'name' => $name,
+                            'delimiter' => $this->delimiter,
+                            'method' => $method->getName(),
+                            'description' => $attributes?->description,
+                            'params' => $attributes?->params,
+                            'result' => $attributes?->result,
+                            'request' => $this->highlight($request),
+                            'response' => $this->highlight($response),
+                        ];
+                    });
+            })
+            ->flatten(1);
+    }
+
+    private function getMethodAnnotations(ReflectionMethod $method): ?RpcMethod
+    {
+        $attributes = $method->getAttributes(RpcMethod::class, \ReflectionAttribute::IS_INSTANCEOF);
+
+        foreach ($attributes as $attribute) {
+            /** @var RpcMethod $instance */
+            $instance = $attribute->newInstance();
+
+            return $instance;
+        }
+
+        return null;
+    }
+
+    /**
+     * Highlights a JSON structure using HTML span tags with colors.
+     *
+     * @param array $value The JSON data to be highlighted.
+     *
+     * @return \Illuminate\Support\Stringable The highlighted JSON as a string.
+     * @throws \JsonException If encoding fails.
+     *
+     */
+    private function highlight(array $value): Stringable
+    {
+        $json = json_encode($value, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
+
+        return Str::of($json)
+            // Highlight keys (both string and numeric)
+            ->replaceMatches('/"(\w+)":/i', '"<span style="color:#A0AEC0;">$1</span>":')
+            ->replaceMatches('/"(\d+)":/i', '"<span style="color:#A0AEC0;">$1</span>":')
+
+            // Highlight null values
+            ->replaceMatches('/":\s*(null)/i', '": <span style="color:#F7768E;">$1</span>')
+
+            // Highlight string values
+            ->replaceMatches('/":\s*"([^"]*)"/', '": "<span style="color:#9ECE6A;">$1</span>"')
+
+            // Highlight numeric values
+            ->replaceMatches('/":\s*(\d+(\.\d+)?)/', '": <span style="color:#E0AF68;">$1</span>')
+
+            // Highlight boolean values (true/false)
+            ->replaceMatches('/":\s*(true|false)/i', '": <span style="color:#7AA2F7;">$1</span>')
+            ->wrap('<pre style="color:rgba(212,212,212,0.75);">', '</pre>');
+    }
+}

app/Console/Commands/DocsCommand.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\Facades\Storage;
+
+/** @deprecated Remove as soon as this pull-request is accepted : https://github.com/sajya/server/pull/87 */
+class DocsCommand extends \Sajya\Server\Commands\DocsCommand
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'cywise:docs {route}
+                                        {--name=docs.html : Name of the generated documentation}
+                                        {--path=/api/ : Path where included documentation files are located}';
+
+    /**
+     * Execute the console command.
+     *
+     * @return int
+     * @throws \Throwable
+     */
+    public function handle(): int
+    {
+        $routeName = $this->argument('route');
+
+        $route = Route::getRoutes()->getByName($routeName);
+
+        if ($route === null) {
+            $this->warn("Route '$routeName' not found");
+
+            return 1;
+        }
+
+        $docs = new Docs($route);
+
+        $html = view('sajya::docs', [
+            'title' => config('app.name'),
+            'uri' => route($routeName),
+            'procedures' => $docs->getAnnotations(),
+        ]);
+
+        Storage::disk()->put($this->option('path') . $this->option('name'), $html->render());
+        $this->info('Documentation was generated successfully.');
+
+        return Command::SUCCESS;
+    }
+}

towerify/Dockerfile

@@ -155,8 +155,8 @@ COPY --chown=www-data:www-data --from=frontend /app/public/build/ /var/www/html/
 RUN chmod -R ug+rwx /var/www/html/storage /var/www/html/bootstrap/cache
 
 # Generate API docs
-RUN php artisan sajya:docs 'v2.public.rpc.endpoint' --path='/public/docs/' --name 'docs.public.html'
-RUN php artisan sajya:docs 'v2.private.rpc.endpoint' --path='/public/docs/' --name 'docs.private.html'
+RUN php artisan cywise:docs 'v2.public.rpc.endpoint' --path='/public/docs/' --name 'docs.public.html'
+RUN php artisan cywise:docs 'v2.private.rpc.endpoint' --path='/public/docs/' --name 'docs.private.html'
 
 COPY <<-EOT /etc/apache2/sites-available/laravel.conf
 <VirtualHost *:80>