Add OpenApi interface

Author: Yoyasp

app/Console/Commands/ApiOpenApiCommand.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\Console\LnmsCommand;
+use App\Services\Api\OpenApi\OpenApiGenerator;
+use GoldSpecDigital\ObjectOrientedOAS\Exceptions\ValidationException;
+use Symfony\Component\Console\Input\InputOption;
+
+class ApiOpenApiCommand extends LnmsCommand
+{
+    protected $name = 'api:openapi';
+    protected $description = 'Generate the OpenAPI 3 specification for the v1 API';
+
+    public function __construct()
+    {
+        parent::__construct();
+
+        $this->addOption('output', null, InputOption::VALUE_REQUIRED, 'Write the spec to PATH instead of stdout');
+        $this->addOption('validate', null, InputOption::VALUE_NONE, 'Validate the spec and exit non-zero on errors');
+        $this->addOption('no-pretty', null, InputOption::VALUE_NONE, 'Emit compact JSON');
+    }
+
+    public function handle(OpenApiGenerator $generator): int
+    {
+        $spec = $generator->generate();
+
+        if ($this->option('validate')) {
+            try {
+                $spec->validate();
+            } catch (ValidationException $e) {
+                $this->error($e->getMessage());
+
+                return 1;
+            }
+        }
+
+        $flags = $this->option('no-pretty') ? 0 : JSON_PRETTY_PRINT;
+        $json = $spec->toJson($flags);
+
+        $output = $this->option('output');
+        if ($output !== null) {
+            file_put_contents($output, $json);
+            $this->info("Wrote {$output}");
+
+            return 0;
+        }
+
+        $this->line($json);
+
+        return 0;
+    }
+}

app/Http/Controllers/Api/V1/OpenApiController.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Services\Api\OpenApi\OpenApiGenerator;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\View\View;
+
+class OpenApiController extends Controller
+{
+    public function __construct(private readonly OpenApiGenerator $generator)
+    {
+    }
+
+    public function spec(Request $request): JsonResponse
+    {
+        $array = $request->boolean('fresh')
+            ? $this->generator->generate()->toArray()
+            : Cache::remember(
+                'api.v1.openapi.spec',
+                300,
+                fn () => $this->generator->generate()->toArray(),
+            );
+
+        return new JsonResponse($array);
+    }
+
+    public function docs(): View
+    {
+        return view('api.v1.docs', [
+            'specUrl' => route('v1.openapi'),
+            'cdnUrl' => 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5',
+        ]);
+    }
+}

app/Http/Controllers/ApiAccessController.php

@@ -24,10 +24,12 @@
 namespace App\Http\Controllers;
 
 use App\Models\ApiToken;
+use App\Models\User;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
+use Laravel\Sanctum\PersonalAccessToken;
 use LibreNMS\Authentication\LegacyAuth;
 
 class ApiAccessController extends Controller
@@ -46,8 +48,15 @@ public function index(Request $request): View
             ->orderBy('id')
             ->get();
 
+        $v1Tokens = PersonalAccessToken::query()
+            ->where('tokenable_type', User::class)
+            ->where('tokenable_id', $user->user_id)
+            ->orderBy('id')
+            ->get();
+
         return view('user.api-access', [
             'tokens' => $tokens,
+            'v1_tokens' => $v1Tokens,
             'legacy_auth_type' => LegacyAuth::getType(),
         ]);
     }

app/Models/AlertRule.php

@@ -71,6 +71,12 @@ protected static function booted(): void
         'extra' => 'array',
     ];
 
+    protected $attributes = [
+        'extra' => '{}',
+        'builder' => '{}',
+        'query' => '',
+    ];
+
     // ---- Query scopes ----
 
     /**

app/Providers/RestifyServiceProvider.php

@@ -80,6 +80,7 @@
 use App\Restify\VrfLiteRepository;
 use App\Restify\VrfRepository;
 use App\Http\Controllers\Api\V1\HealthController;
+use App\Http\Controllers\Api\V1\OpenApiController;
 use App\Http\Controllers\Api\V1\SystemController;
 use Binaryk\LaravelRestify\Bootstrap\RoutesBoot;
 use Binaryk\LaravelRestify\Restify;
@@ -105,6 +106,8 @@ protected function routes(): void
             Route::get('system', SystemController::class)
                 ->middleware(['auth:sanctum', 'can:settings.view'])
                 ->name('v1.system');
+            Route::get('openapi.json', [OpenApiController::class, 'spec'])->name('v1.openapi');
+            Route::get('docs', [OpenApiController::class, 'docs'])->name('v1.docs');
         });
 
         parent::routes();

app/Restify/AlertRepository.php

@@ -21,6 +21,8 @@ class AlertRepository extends Repository
 
     public static string $title = 'id';
 
+    protected static array $disabledActions = ['update'];
+
 
 
 

app/Restify/Repository.php

@@ -9,9 +9,18 @@
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Gate;
+use ReflectionMethod;
 
 abstract class Repository extends RestifyRepository
 {
+    /**
+     * Actions to suppress from the OpenAPI document and (by convention) from custom routes().
+     * Subclasses may override with any of: 'store', 'update', 'destroy'.
+     *
+     * @var string[]
+     */
+    protected static array $disabledActions = [];
+
     public static function authorizedToUseRepository(Request $request): bool
     {
         $user = $request->user();
@@ -37,4 +46,52 @@ public static function showQuery(RestifyRequest $request, Builder|Relation $quer
     {
         return $query;
     }
+
+    /**
+     * Whether the action should appear in the OpenAPI document. Combines the explicit
+     * $disabledActions list, any LibreNMS-side authorizedTo<Action> override (which by
+     * convention returns false unconditionally), and policy method existence.
+     */
+    public static function actionEnabled(string $action): bool
+    {
+        if (in_array($action, static::$disabledActions, true)) {
+            return false;
+        }
+
+        $authMethod = match ($action) {
+            'store' => 'authorizedToStore',
+            'update' => 'authorizedToUpdate',
+            'destroy' => 'authorizedToDelete',
+            default => null,
+        };
+
+        $policyMethod = match ($action) {
+            'store' => 'create',
+            'update' => 'update',
+            'destroy' => 'delete',
+            default => null,
+        };
+
+        if ($authMethod === null || $policyMethod === null) {
+            return false;
+        }
+
+        $declaringClass = (new ReflectionMethod(static::class, $authMethod))->getDeclaringClass()->getName();
+        if ($declaringClass !== self::class && str_starts_with($declaringClass, 'App\\Restify\\')) {
+            return false;
+        }
+
+        if (! property_exists(static::class, 'model')) {
+            return false;
+        }
+        /** @var class-string<\Illuminate\Database\Eloquent\Model>|null $modelClass */
+        $modelClass = static::$model ?? null; // @phpstan-ignore staticProperty.notFound
+        if (! is_string($modelClass) || ! class_exists($modelClass)) {
+            return false;
+        }
+
+        $policy = Gate::getPolicyFor(new $modelClass());
+
+        return is_object($policy) && method_exists($policy, $policyMethod);
+    }
 }