banquise/pelican-panel-mirror
3
0
Fork 1
mirror of https://github.com/pelican-dev/panel.git synced 2025-05-20 01:44:45 +02:00
Code Issues Packages Projects Releases Wiki Activity

Small api docs improvements (#1032)

Browse Source 
* update scramble

* cleanup application api endpoints

* cleanup client api endpoints

* fix security schema and make docs homepage nicer

* remove duplicate myclabs/deep-copy

* style(api-docs): use Blade template and Tailwind for styling

* Publish scramble view

* Use localStorage theme instead of config

* Update routes/docs.php

Co-authored-by: Lance Pioch <git@lance.sh>

---------

Co-authored-by: Quinten <67589015+QuintenQVD0@users.noreply.github.com>
Co-authored-by: RMartinOscar <40749467+RMartinOscar@users.noreply.github.com>
Co-authored-by: Lance Pioch <git@lance.sh>
This commit is contained in:
Boy132 2025-02-26 16:12:19 +01:00 committed by GitHub
parent 2d937229fb
commit e1308cb04d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
44 changed files with 436 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
app/Http/Controllers/Api/Application/DatabaseHosts/DatabaseHostController.php
View File

@ -28,6 +28,8 @@ class DatabaseHostController extends ApplicationApiController
}
/**
* List database hosts
*
* Return all the database hosts currently registered on the Panel.
*/
public function index(GetDatabaseHostRequest $request): array
@ -43,6 +45,8 @@ class DatabaseHostController extends ApplicationApiController
}
/**
* View database host
*
* Return a single database host.
*/
public function view(GetDatabaseHostRequest $request, DatabaseHost $databaseHost): array
@ -53,6 +57,8 @@ class DatabaseHostController extends ApplicationApiController
}
/**
* Create database host
*
* Store a new database host on the Panel and return an HTTP/201 response code with the
* new database host attached.
*
@ -73,6 +79,8 @@ class DatabaseHostController extends ApplicationApiController
}
/**
* Update database host
*
* Update a database host on the Panel and return the updated record to the user.
*
* @throws \Throwable
@ -87,6 +95,8 @@ class DatabaseHostController extends ApplicationApiController
}
/**
* Delete database host
*
* Delete a database host from the Panel.
*
* @throws \Exception

4
app/Http/Controllers/Api/Application/Eggs/EggController.php
View File

@ -11,6 +11,8 @@ use App\Transformers\Api\Application\EggTransformer;
class EggController extends ApplicationApiController
{
/**
* List eggs
*
* Return all eggs
*/
public function index(GetEggsRequest $request): array
@ -21,6 +23,8 @@ class EggController extends ApplicationApiController
}
/**
* View egg
*
* Return a single egg that exists
*/
public function view(GetEggRequest $request, Egg $egg): array

18
app/Http/Controllers/Api/Application/Mounts/MountController.php
View File

@ -18,6 +18,8 @@ use App\Exceptions\Service\HasActiveServersException;
class MountController extends ApplicationApiController
{
/**
* List mounts
*
* Return all the mounts currently available on the Panel.
*/
public function index(GetMountRequest $request): array
@ -33,6 +35,8 @@ class MountController extends ApplicationApiController
}
/**
* View mount
*
* Return data for a single instance of a mount.
*/
public function view(GetMountRequest $request, Mount $mount): array
@ -43,6 +47,8 @@ class MountController extends ApplicationApiController
}
/**
* Create mount
*
* Create a new mount on the Panel. Returns the created mount and an HTTP/201
* status response on success.
*
@ -67,6 +73,8 @@ class MountController extends ApplicationApiController
}
/**
* Update mount
*
* Update an existing mount on the Panel.
*
* @throws \Throwable
@ -81,6 +89,8 @@ class MountController extends ApplicationApiController
}
/**
* Delete mount
*
* Deletes a given mount from the Panel as long as there are no servers
* currently attached to it.
*
@ -98,6 +108,8 @@ class MountController extends ApplicationApiController
}
/**
* Assign eggs to mount
*
* Adds eggs to the mount's many-to-many relation.
*/
public function addEggs(Request $request, Mount $mount): array
@ -117,6 +129,8 @@ class MountController extends ApplicationApiController
}
/**
* Assign mounts to mount
*
* Adds nodes to the mount's many-to-many relation.
*/
public function addNodes(Request $request, Mount $mount): array
@ -134,6 +148,8 @@ class MountController extends ApplicationApiController
}
/**
* Unassign egg from mount
*
* Deletes an egg from the mount's many-to-many relation.
*/
public function deleteEgg(Mount $mount, int $egg_id): JsonResponse
@ -144,6 +160,8 @@ class MountController extends ApplicationApiController
}
/**
* Unassign node from mount
*
* Deletes a node from the mount's many-to-many relation.
*/
public function deleteNode(Mount $mount, int $node_id): JsonResponse

8
app/Http/Controllers/Api/Application/Nodes/AllocationController.php
View File

@ -14,7 +14,9 @@ use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Allocations\GetAllocationsRequest;
use App\Http\Requests\Api\Application\Allocations\StoreAllocationRequest;
use App\Http\Requests\Api\Application\Allocations\DeleteAllocationRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Node - Allocation')]
class AllocationController extends ApplicationApiController
{
/**
@ -27,6 +29,8 @@ class AllocationController extends ApplicationApiController
}
/**
* List allocations
*
* Return all the allocations that exist for a given node.
*/
public function index(GetAllocationsRequest $request, Node $node): array
@ -52,6 +56,8 @@ class AllocationController extends ApplicationApiController
}
/**
* Create allocation
*
* Store new allocations for a given node.
*
* @throws \App\Exceptions\DisplayException
@ -68,6 +74,8 @@ class AllocationController extends ApplicationApiController
}
/**
* Delete allocation
*
* Delete a specific allocation from the Panel.
*/
public function delete(DeleteAllocationRequest $request, Node $node, Allocation $allocation): JsonResponse

4
app/Http/Controllers/Api/Application/Nodes/NodeConfigurationController.php
View File

@ -6,10 +6,14 @@ use App\Models\Node;
use Illuminate\Http\JsonResponse;
use App\Http\Requests\Api\Application\Nodes\GetNodeRequest;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use Dedoc\Scramble\Attributes\Group;
#[Group('Node', weight: 1)]
class NodeConfigurationController extends ApplicationApiController
{
/**
* Get node configuration
*
* Returns the configuration information for a node. This allows for automated deployments
* to remote machines so long as an API key is provided to the machine to make the request
* with, and the node is known.

12
app/Http/Controllers/Api/Application/Nodes/NodeController.php
View File

@ -15,7 +15,9 @@ use App\Http\Requests\Api\Application\Nodes\StoreNodeRequest;
use App\Http\Requests\Api\Application\Nodes\DeleteNodeRequest;
use App\Http\Requests\Api\Application\Nodes\UpdateNodeRequest;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use Dedoc\Scramble\Attributes\Group;
#[Group('Node', weight: 0)]
class NodeController extends ApplicationApiController
{
/**
@ -30,6 +32,8 @@ class NodeController extends ApplicationApiController
}
/**
* List nodes
*
* Return all the nodes currently available on the Panel.
*/
public function index(GetNodesRequest $request): array
@ -45,6 +49,8 @@ class NodeController extends ApplicationApiController
}
/**
* View node
*
* Return data for a single instance of a node.
*/
public function view(GetNodeRequest $request, Node $node): array
@ -55,6 +61,8 @@ class NodeController extends ApplicationApiController
}
/**
* Create node
*
* Create a new node on the Panel. Returns the created node and an HTTP/201
* status response on success.
*
@ -75,6 +83,8 @@ class NodeController extends ApplicationApiController
}
/**
* Update node
*
* Update an existing node on the Panel.
*
* @throws \Throwable
@ -93,6 +103,8 @@ class NodeController extends ApplicationApiController
}
/**
* Delete node
*
* Deletes a given node from the Panel as long as there are no servers
* currently attached to it.
*

4
app/Http/Controllers/Api/Application/Nodes/NodeDeploymentController.php
View File

@ -6,7 +6,9 @@ use App\Services\Deployment\FindViableNodesService;
use App\Transformers\Api\Application\NodeTransformer;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Nodes\GetDeployableNodesRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Node', weight: 2)]
class NodeDeploymentController extends ApplicationApiController
{
public function __construct(private FindViableNodesService $viableNodesService)
@ -15,6 +17,8 @@ class NodeDeploymentController extends ApplicationApiController
}
/**
* Get deployable nodes
*
* Finds any nodes that are available using the given deployment criteria. This works
* similarly to the server creation process, but allows you to pass the deployment object
* to this endpoint and get back a list of all Nodes satisfying the requirements.

10
app/Http/Controllers/Api/Application/Roles/RoleController.php
View File

@ -17,6 +17,8 @@ use App\Http\Requests\Api\Application\Roles\UpdateRoleRequest;
class RoleController extends ApplicationApiController
{
/**
* List roles
*
* Return all the roles currently registered on the Panel.
*/
public function index(GetRoleRequest $request): array
@ -32,6 +34,8 @@ class RoleController extends ApplicationApiController
}
/**
* View role
*
* Return a single role.
*/
public function view(GetRoleRequest $request, Role $role): array
@ -42,6 +46,8 @@ class RoleController extends ApplicationApiController
}
/**
* Create role
*
* Store a new role on the Panel and return an HTTP/201 response code with the
* new role attached.
*
@ -62,6 +68,8 @@ class RoleController extends ApplicationApiController
}
/**
* Update role
*
* Update a role on the Panel and return the updated record to the user.
*
* @throws \Throwable
@ -80,6 +88,8 @@ class RoleController extends ApplicationApiController
}
/**
* Delete role
*
* Delete a role from the Panel.
*
* @throws \Exception

12
app/Http/Controllers/Api/Application/Servers/DatabaseController.php
View File

@ -14,7 +14,9 @@ use App\Http\Requests\Api\Application\Servers\Databases\GetServerDatabaseRequest
use App\Http\Requests\Api\Application\Servers\Databases\GetServerDatabasesRequest;
use App\Http\Requests\Api\Application\Servers\Databases\ServerDatabaseWriteRequest;
use App\Http\Requests\Api\Application\Servers\Databases\StoreServerDatabaseRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Database')]
class DatabaseController extends ApplicationApiController
{
/**
@ -28,6 +30,8 @@ class DatabaseController extends ApplicationApiController
}
/**
* List databases
*
* Return a listing of all databases currently available to a single
* server.
*/
@ -39,6 +43,8 @@ class DatabaseController extends ApplicationApiController
}
/**
* View database
*
* Return a single server database.
*/
public function view(GetServerDatabaseRequest $request, Server $server, Database $database): array
@ -49,6 +55,8 @@ class DatabaseController extends ApplicationApiController
}
/**
* Reset password
*
* Reset the password for a specific server database.
*
* @throws \Throwable
@ -61,6 +69,8 @@ class DatabaseController extends ApplicationApiController
}
/**
* Create database
*
* Create a new database on the Panel for a given server.
*
* @throws \Throwable
@ -83,6 +93,8 @@ class DatabaseController extends ApplicationApiController
}
/**
* Delete database
*
* Handle a request to delete a specific server database from the Panel.
*/
public function delete(ServerDatabaseWriteRequest $request, Server $server, Database $database): Response

4
app/Http/Controllers/Api/Application/Servers/ExternalServerController.php
View File

@ -6,10 +6,14 @@ use App\Models\Server;
use App\Transformers\Api\Application\ServerTransformer;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Servers\GetExternalServerRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server', weight: 1)]
class ExternalServerController extends ApplicationApiController
{
/**
* View server (external id)
*
* Retrieve a specific server from the database using its external ID.
*/
public function index(GetExternalServerRequest $request, string $external_id): array

10
app/Http/Controllers/Api/Application/Servers/ServerController.php
View File

@ -14,7 +14,9 @@ use App\Http\Requests\Api\Application\Servers\GetServersRequest;
use App\Http\Requests\Api\Application\Servers\ServerWriteRequest;
use App\Http\Requests\Api\Application\Servers\StoreServerRequest;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server', weight: 0)]
class ServerController extends ApplicationApiController
{
/**
@ -28,6 +30,8 @@ class ServerController extends ApplicationApiController
}
/**
* List servers
*
* Return all the servers that currently exist on the Panel.
*/
public function index(GetServersRequest $request): array
@ -43,6 +47,8 @@ class ServerController extends ApplicationApiController
}
/**
* Create server
*
* Create a new server on the system.
*
* @throws \Throwable
@ -61,6 +67,8 @@ class ServerController extends ApplicationApiController
}
/**
* View server
*
* Show a single server transformed for the application API.
*/
public function view(GetServerRequest $request, Server $server): array
@ -71,6 +79,8 @@ class ServerController extends ApplicationApiController
}
/**
* Delete server
*
* Deletes a server.
*
* @throws \App\Exceptions\DisplayException

6
app/Http/Controllers/Api/Application/Servers/ServerDetailsController.php
View File

@ -9,7 +9,9 @@ use App\Transformers\Api\Application\ServerTransformer;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Servers\UpdateServerDetailsRequest;
use App\Http\Requests\Api\Application\Servers\UpdateServerBuildConfigurationRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server', weight: 2)]
class ServerDetailsController extends ApplicationApiController
{
/**
@ -23,6 +25,8 @@ class ServerDetailsController extends ApplicationApiController
}
/**
* Update details
*
* Update the details for a specific server.
*
* @throws \App\Exceptions\DisplayException
@ -41,6 +45,8 @@ class ServerDetailsController extends ApplicationApiController
}
/**
* Update build
*
* Update the build details for a specific server.
*
* @throws \App\Exceptions\DisplayException

12
app/Http/Controllers/Api/Application/Servers/ServerManagementController.php
View File

@ -10,9 +10,11 @@ use App\Repositories\Daemon\DaemonServerRepository;
use App\Services\Servers\ReinstallServerService;
use App\Services\Servers\SuspensionService;
use App\Services\Servers\TransferServerService;
use Dedoc\Scramble\Attributes\Group;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Response;
#[Group('Server', weight: 4)]
class ServerManagementController extends ApplicationApiController
{
/**
@ -28,6 +30,8 @@ class ServerManagementController extends ApplicationApiController
}
/**
* Suspsend
*
* Suspend a server on the Panel.
*
* @throws \Throwable
@ -40,6 +44,8 @@ class ServerManagementController extends ApplicationApiController
}
/**
* Unsuspsend
*
* Unsuspend a server on the Panel.
*
* @throws \Throwable
@ -52,6 +58,8 @@ class ServerManagementController extends ApplicationApiController
}
/**
* Reinstall
*
* Mark a server as needing to be reinstalled.
*
* @throws \App\Exceptions\DisplayException
@ -65,6 +73,8 @@ class ServerManagementController extends ApplicationApiController
}
/**
* Start transfer
*
* Starts a transfer of a server to a new node.
*/
public function startTransfer(ServerWriteRequest $request, Server $server): Response
@ -85,6 +95,8 @@ class ServerManagementController extends ApplicationApiController
}
/**
* Cancel transfer
*
* Cancels a transfer of a server to a new node.
*
* @throws ConnectionException

4
app/Http/Controllers/Api/Application/Servers/StartupController.php
View File

@ -9,9 +9,11 @@ use App\Services\Servers\StartupModificationService;
use App\Transformers\Api\Application\ServerTransformer;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Servers\UpdateServerStartupRequest;
use Dedoc\Scramble\Attributes\Group;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Validation\ValidationException;
#[Group('Server', weight: 3)]
class StartupController extends ApplicationApiController
{
/**
@ -23,6 +25,8 @@ class StartupController extends ApplicationApiController
}
/**
* Update startup
*
* Update the startup and environment settings for a specific server.
*
* @throws ValidationException

4
app/Http/Controllers/Api/Application/Users/ExternalUserController.php
View File

@ -6,10 +6,14 @@ use App\Models\User;
use App\Transformers\Api\Application\UserTransformer;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Users\GetExternalUserRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('User', weight: 1)]
class ExternalUserController extends ApplicationApiController
{
/**
* View user (external id)
*
* Retrieve a specific user from the database using their external ID.
*/
public function index(GetExternalUserRequest $request, string $external_id): array

16
app/Http/Controllers/Api/Application/Users/UserController.php
View File

@ -15,7 +15,9 @@ use App\Http\Requests\Api\Application\Users\UpdateUserRequest;
use App\Http\Controllers\Api\Application\ApplicationApiController;
use App\Http\Requests\Api\Application\Users\AssignUserRolesRequest;
use App\Models\Role;
use Dedoc\Scramble\Attributes\Group;
#[Group('User', weight: 0)]
class UserController extends ApplicationApiController
{
/**
@ -29,6 +31,8 @@ class UserController extends ApplicationApiController
}
/**
* List users
*
* Handle request to list all users on the panel. Returns a JSON-API representation
* of a collection of users including any defined relations passed in
* the request.
@ -46,6 +50,8 @@ class UserController extends ApplicationApiController
}
/**
* View user
*
* Handle a request to view a single user. Includes any relations that
* were defined in the request.
*/
@ -57,6 +63,8 @@ class UserController extends ApplicationApiController
}
/**
* Update user
*
* Update an existing user on the system and return the response. Returns the
* updated user model response on success. Supports handling of token revocation
* errors when switching a user from an admin to a normal user.
@ -78,6 +86,8 @@ class UserController extends ApplicationApiController
}
/**
* Assign role to user
*
* Assign roles to a user.
*/
public function assignRoles(AssignUserRolesRequest $request, User $user): array
@ -97,6 +107,8 @@ class UserController extends ApplicationApiController
}
/**
* Unassign role from user
*
* Removes roles from a user.
*/
public function removeRoles(AssignUserRolesRequest $request, User $user): array
@ -116,6 +128,8 @@ class UserController extends ApplicationApiController
}
/**
* Create user
*
* Store a new user on the system. Returns the created user and an HTTP/201
* header on successful creation.
*
@ -137,6 +151,8 @@ class UserController extends ApplicationApiController
}
/**
* Delete user
*
* Handle a request to delete a user from the Panel. Returns a HTTP/204 response on successful deletion.
*/
public function delete(DeleteUserRequest $request, User $user): JsonResponse

7
app/Http/Controllers/Api/Client/AccountController.php
View File

@ -23,6 +23,9 @@ class AccountController extends ClientApiController
parent::__construct();
}
/**
* View account
*/
public function index(Request $request): array
{
return $this->fractal->item($request->user())
@ -31,6 +34,8 @@ class AccountController extends ClientApiController
}
/**
* Update email
*
* Update the authenticated user's email address.
*/
public function updateEmail(UpdateEmailRequest $request): JsonResponse
@ -48,6 +53,8 @@ class AccountController extends ClientApiController
}
/**
* Update password
*
* Update the authenticated user's password. All existing sessions will be logged
* out immediately.
*

2
app/Http/Controllers/Api/Client/ActivityLogController.php
View File

@ -11,6 +11,8 @@ use App\Transformers\Api\Client\ActivityLogTransformer;
class ActivityLogController extends ClientApiController
{
/**
* List activity logs
*
* Returns a paginated set of the user's activity logs.
*/
public function __invoke(ClientApiRequest $request): array

6
app/Http/Controllers/Api/Client/ApiKeyController.php
View File

@ -13,6 +13,8 @@ use App\Http\Requests\Api\Client\Account\StoreApiKeyRequest;
class ApiKeyController extends ClientApiController
{
/**
* List api keys
*
* Returns all the API keys that exist for the given client.
*/
public function index(ClientApiRequest $request): array
@ -23,6 +25,8 @@ class ApiKeyController extends ClientApiController
}
/**
* Create api key
*
* Store a new API key for a user's account.
*
* @throws \App\Exceptions\DisplayException
@ -50,6 +54,8 @@ class ApiKeyController extends ClientApiController
}
/**
* Delete api key
*
* Deletes a given API key.
*/
public function delete(ClientApiRequest $request, string $identifier): JsonResponse

6
app/Http/Controllers/Api/Client/ClientController.php
View File

@ -9,7 +9,9 @@ use Spatie\QueryBuilder\AllowedFilter;
use App\Models\Filters\MultiFieldServerFilter;
use App\Transformers\Api\Client\ServerTransformer;
use App\Http\Requests\Api\Client\GetServersRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Base')]
class ClientController extends ClientApiController
{
/**
@ -21,6 +23,8 @@ class ClientController extends ClientApiController
}
/**
* List servers
*
* Return all the servers available to the client making the API
* request, including servers the user has access to as a subuser.
*/
@ -67,6 +71,8 @@ class ClientController extends ClientApiController
}
/**
* List subuser permissions
*
* Returns all the subuser permissions available on the system.
*/
public function permissions(): array

6
app/Http/Controllers/Api/Client/SSHKeyController.php
View File

@ -11,6 +11,8 @@ use App\Http\Requests\Api\Client\Account\StoreSSHKeyRequest;
class SSHKeyController extends ClientApiController
{
/**
* List ssh keys
*
* Returns all the SSH keys that have been configured for the logged-in
* user account.
*/
@ -22,6 +24,8 @@ class SSHKeyController extends ClientApiController
}
/**
* Create ssh keys
*
* Stores a new SSH key for the authenticated user's account.
*/
public function store(StoreSSHKeyRequest $request): array
@ -43,6 +47,8 @@ class SSHKeyController extends ClientApiController
}
/**
* Delete ssh keys
*
* Deletes an SSH key from the user's account.
*/
public function delete(ClientApiRequest $request): JsonResponse

4
app/Http/Controllers/Api/Client/Servers/ActivityLogController.php
View File

@ -14,10 +14,14 @@ use App\Http\Requests\Api\Client\ClientApiRequest;
use App\Transformers\Api\Client\ActivityLogTransformer;
use App\Http\Controllers\Api\Client\ClientApiController;
use App\Models\Role;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Activity log')]
class ActivityLogController extends ClientApiController
{
/**
* List activity logs
*
* Returns the activity logs for a server.
*/
public function __invoke(ClientApiRequest $request, Server $server): array

16
app/Http/Controllers/Api/Client/Servers/BackupController.php
View File

@ -19,7 +19,9 @@ use App\Http\Controllers\Api\Client\ClientApiController;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use App\Http\Requests\Api\Client\Servers\Backups\StoreBackupRequest;
use App\Http\Requests\Api\Client\Servers\Backups\RestoreBackupRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Backup')]
class BackupController extends ClientApiController
{
public function __construct(
@ -32,6 +34,8 @@ class BackupController extends ClientApiController
}
/**
* List backups
*
* Returns all the backups for a given server instance in a paginated
* result set.
*
@ -54,6 +58,8 @@ class BackupController extends ClientApiController
}
/**
* Create backup
*
* Starts the backup process for a server.
*
* @throws \Spatie\Fractalistic\Exceptions\InvalidTransformation
@ -86,6 +92,8 @@ class BackupController extends ClientApiController
}
/**
* Toggle lock
*
* Toggles the lock status of a given backup for a server.
*
* @throws \Throwable
@ -109,6 +117,8 @@ class BackupController extends ClientApiController
}
/**
* View backup
*
* Returns information about a single backup.
*
* @throws \Illuminate\Auth\Access\AuthorizationException
@ -125,6 +135,8 @@ class BackupController extends ClientApiController
}
/**
* Delete backup
*
* Deletes a backup from the panel as well as the remote source where it is currently
* being stored.
*
@ -147,6 +159,8 @@ class BackupController extends ClientApiController
}
/**
* Download backup
*
* Download the backup for a given server instance. For daemon local files, the file
* will be streamed back through the Panel. For AWS S3 files, a signed URL will be generated
* which the user is redirected to.
@ -175,6 +189,8 @@ class BackupController extends ClientApiController
}
/**
* Restore backup
*
* Handles restoring a backup by making a request to the daemon instance telling it
* to begin the process of finding (or downloading) the backup and unpacking it
* over the server files.

4
app/Http/Controllers/Api/Client/Servers/CommandController.php
View File

@ -9,12 +9,16 @@ use GuzzleHttp\Exception\BadResponseException;
use Symfony\Component\HttpKernel\Exception\HttpException;
use App\Http\Controllers\Api\Client\ClientApiController;
use App\Http\Requests\Api\Client\Servers\SendCommandRequest;
use Dedoc\Scramble\Attributes\Group;
use Exception;
use Illuminate\Http\Client\ConnectionException;
#[Group('Server', weight: 1)]
class CommandController extends ClientApiController
{
/**
* Send command
*
* Send a command to a running server.
*
* @throws ConnectionException

10
app/Http/Controllers/Api/Client/Servers/DatabaseController.php
View File

@ -15,7 +15,9 @@ use App\Http\Requests\Api\Client\Servers\Databases\GetDatabasesRequest;
use App\Http\Requests\Api\Client\Servers\Databases\StoreDatabaseRequest;
use App\Http\Requests\Api\Client\Servers\Databases\DeleteDatabaseRequest;
use App\Http\Requests\Api\Client\Servers\Databases\RotatePasswordRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Database')]
class DatabaseController extends ClientApiController
{
/**
@ -30,6 +32,8 @@ class DatabaseController extends ClientApiController
}
/**
* List databases
*
* Return all the databases that belong to the given server.
*/
public function index(GetDatabasesRequest $request, Server $server): array
@ -40,6 +44,8 @@ class DatabaseController extends ClientApiController
}
/**
* Create database
*
* Create a new database for the given server and return it.
*
* @throws \Throwable
@ -62,6 +68,8 @@ class DatabaseController extends ClientApiController
}
/**
* Rotate password
*
* Rotates the password for the given server model and returns a fresh instance to
* the caller.
*
@ -84,6 +92,8 @@ class DatabaseController extends ClientApiController
}
/**
* Delete database
*
* Removes a database from the server.
*/
public function delete(DeleteDatabaseRequest $request, Server $server, Database $database): Response

26
app/Http/Controllers/Api/Client/Servers/FileController.php
View File

@ -22,8 +22,10 @@ use App\Http\Requests\Api\Client\Servers\Files\CompressFilesRequest;
use App\Http\Requests\Api\Client\Servers\Files\DecompressFilesRequest;
use App\Http\Requests\Api\Client\Servers\Files\GetFileContentsRequest;
use App\Http\Requests\Api\Client\Servers\Files\WriteFileContentRequest;
use Dedoc\Scramble\Attributes\Group;
use Illuminate\Http\Client\ConnectionException;
#[Group('Server - File', weight: 0)]
class FileController extends ClientApiController
{
/**
@ -37,6 +39,8 @@ class FileController extends ClientApiController
}
/**
* List files
*
* Returns a listing of files in a given directory.
*
* @throws ConnectionException
@ -53,6 +57,8 @@ class FileController extends ClientApiController
}
/**
* View file
*
* Return the contents of a specified file for the user.
*
* @throws \Throwable
@ -72,6 +78,8 @@ class FileController extends ClientApiController
}
/**
* Download file
*
* Generates a one-time token with a link that the user can use to
* download a given file.
*
@ -103,6 +111,8 @@ class FileController extends ClientApiController
}
/**
* Write file
*
* Writes the contents of the specified file to the server.
*
* @throws ConnectionException
@ -121,6 +131,8 @@ class FileController extends ClientApiController
}
/**
* Create directory
*
* Creates a new folder on the server.
*
* @throws \Throwable
@ -140,6 +152,8 @@ class FileController extends ClientApiController
}
/**
* Rename file
*
* Renames a file on the remote machine.
*
* @throws \Throwable
@ -163,6 +177,8 @@ class FileController extends ClientApiController
}
/**
* Copy file
*
* Copies a file on the server.
*
* @throws ConnectionException
@ -181,6 +197,8 @@ class FileController extends ClientApiController
}
/**
* Compress files
*
* @throws ConnectionException
*/
public function compress(CompressFilesRequest $request, Server $server): array
@ -201,6 +219,8 @@ class FileController extends ClientApiController
}
/**
* Decompress files
*
* @throws ConnectionException
*/
public function decompress(DecompressFilesRequest $request, Server $server): JsonResponse
@ -221,6 +241,8 @@ class FileController extends ClientApiController
}
/**
* Delete files/ folders
*
* Deletes files or folders for the server in the given root directory.
*
* @throws ConnectionException
@ -241,6 +263,8 @@ class FileController extends ClientApiController
}
/**
* Update file permissions
*
* Updates file permissions for file(s) in the given root directory.
*
* @throws ConnectionException
@ -256,6 +280,8 @@ class FileController extends ClientApiController
}
/**
* Pull remote file
*
* Requests that a file be downloaded from a remote location by daemon.
*
* @throws \Throwable

4
app/Http/Controllers/Api/Client/Servers/FileUploadController.php
View File

@ -9,7 +9,9 @@ use Illuminate\Http\JsonResponse;
use App\Services\Nodes\NodeJWTService;
use App\Http\Controllers\Api\Client\ClientApiController;
use App\Http\Requests\Api\Client\Servers\Files\UploadFileRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - File', weight: 1)]
class FileUploadController extends ClientApiController
{
/**
@ -22,6 +24,8 @@ class FileUploadController extends ClientApiController
}
/**
* Get upload url
*
* Returns an url where files can be uploaded to.
*/
public function __invoke(UploadFileRequest $request, Server $server): JsonResponse

13
app/Http/Controllers/Api/Client/Servers/NetworkAllocationController.php
View File

@ -15,7 +15,9 @@ use App\Http\Requests\Api\Client\Servers\Network\NewAllocationRequest;
use App\Http\Requests\Api\Client\Servers\Network\DeleteAllocationRequest;
use App\Http\Requests\Api\Client\Servers\Network\UpdateAllocationRequest;
use App\Http\Requests\Api\Client\Servers\Network\SetPrimaryAllocationRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Allocation')]
class NetworkAllocationController extends ClientApiController
{
/**
@ -28,6 +30,8 @@ class NetworkAllocationController extends ClientApiController
}
/**
* List allocations
*
* Lists all the allocations available to a server and whether
* they are currently assigned as the primary for this server.
*/
@ -39,6 +43,8 @@ class NetworkAllocationController extends ClientApiController
}
/**
* Update allocation
*
* Set the primary allocation for a server.
*
* @throws \App\Exceptions\Model\DataValidationException
@ -62,6 +68,8 @@ class NetworkAllocationController extends ClientApiController
}
/**
* Set primar<
*
* Set the primary allocation for a server.
*
* @throws \App\Exceptions\Model\DataValidationException
@ -82,8 +90,9 @@ class NetworkAllocationController extends ClientApiController
}
/**
* Create allocation
*
* Set the notes for the allocation for a server.
*s.
*
* @throws \App\Exceptions\DisplayException
*/
@ -106,6 +115,8 @@ class NetworkAllocationController extends ClientApiController
}
/**
* Delete allocation
*
* Delete an allocation from a server.
*
* @throws \App\Exceptions\DisplayException

4
app/Http/Controllers/Api/Client/Servers/PowerController.php
View File

@ -8,7 +8,9 @@ use App\Facades\Activity;
use App\Repositories\Daemon\DaemonPowerRepository;
use App\Http\Controllers\Api\Client\ClientApiController;
use App\Http\Requests\Api\Client\Servers\SendPowerRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server', weight: 2)]
class PowerController extends ClientApiController
{
/**
@ -20,6 +22,8 @@ class PowerController extends ClientApiController
}
/**
* Send power action
*
* Send a power action to a server.
*/
public function index(SendPowerRequest $request, Server $server): Response

4
app/Http/Controllers/Api/Client/Servers/ResourceUtilizationController.php
View File

@ -9,8 +9,10 @@ use App\Transformers\Api\Client\StatsTransformer;
use App\Repositories\Daemon\DaemonServerRepository;
use App\Http\Controllers\Api\Client\ClientApiController;
use App\Http\Requests\Api\Client\Servers\GetServerRequest;
use Dedoc\Scramble\Attributes\Group;
use Illuminate\Http\Client\ConnectionException;
#[Group('Server', weight: 3)]
class ResourceUtilizationController extends ClientApiController
{
/**
@ -22,6 +24,8 @@ class ResourceUtilizationController extends ClientApiController
}
/**
* View resources
*
* Return the current resource utilization for a server. This value is cached for up to
* 20 seconds at a time to ensure that repeated requests to this endpoint do not cause
* a flood of unnecessary API calls.

14
app/Http/Controllers/Api/Client/Servers/ScheduleController.php
View File

@ -21,7 +21,9 @@ use App\Http\Requests\Api\Client\Servers\Schedules\StoreScheduleRequest;
use App\Http\Requests\Api\Client\Servers\Schedules\DeleteScheduleRequest;
use App\Http\Requests\Api\Client\Servers\Schedules\UpdateScheduleRequest;
use App\Http\Requests\Api\Client\Servers\Schedules\TriggerScheduleRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Schedule', weight: 0)]
class ScheduleController extends ClientApiController
{
/**
@ -33,6 +35,8 @@ class ScheduleController extends ClientApiController
}
/**
* List schedules
*
* Returns all the schedules belonging to a given server.
*/
public function index(ViewScheduleRequest $request, Server $server): array
@ -45,6 +49,8 @@ class ScheduleController extends ClientApiController
}
/**
* Create schedule
*
* Store a new schedule for a server.
*
* @throws \App\Exceptions\DisplayException
@ -77,6 +83,8 @@ class ScheduleController extends ClientApiController
}
/**
* View schedule
*
* Returns a specific schedule for the server.
*/
public function view(ViewScheduleRequest $request, Server $server, Schedule $schedule): array
@ -93,6 +101,8 @@ class ScheduleController extends ClientApiController
}
/**
* Update schedule
*
* Updates a given schedule with the new data provided.
*
* @throws \App\Exceptions\DisplayException
@ -133,6 +143,8 @@ class ScheduleController extends ClientApiController
}
/**
* Run schedule
*
* Executes a given schedule immediately rather than waiting on it's normally scheduled time
* to pass. This does not care about the schedule state.
*
@ -148,6 +160,8 @@ class ScheduleController extends ClientApiController
}
/**
* Delete schedule
*
* Deletes a schedule and it's associated tasks.
*/
public function delete(DeleteScheduleRequest $request, Server $server, Schedule $schedule): JsonResponse

8
app/Http/Controllers/Api/Client/Servers/ScheduleTaskController.php
View File

@ -17,7 +17,9 @@ use App\Http\Controllers\Api\Client\ClientApiController;
use App\Exceptions\Service\ServiceLimitExceededException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use App\Http\Requests\Api\Client\Servers\Schedules\StoreTaskRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Schedule', weight: 1)]
class ScheduleTaskController extends ClientApiController
{
/**
@ -30,6 +32,8 @@ class ScheduleTaskController extends ClientApiController
}
/**
* Create task
*
* Create a new task for a given schedule and store it in the database.
*
* @throws \App\Exceptions\Model\DataValidationException
@ -91,6 +95,8 @@ class ScheduleTaskController extends ClientApiController
}
/**
* Update task
*
* Updates a given task for a server.
*
* @throws \App\Exceptions\Model\DataValidationException
@ -145,6 +151,8 @@ class ScheduleTaskController extends ClientApiController
}
/**
* Delete task
*
* Delete a given task for a schedule. If there are subsequent tasks stored in the database
* for this schedule their sequence IDs are decremented properly.
*

4
app/Http/Controllers/Api/Client/Servers/ServerController.php
View File

@ -7,7 +7,9 @@ use App\Transformers\Api\Client\ServerTransformer;
use App\Services\Servers\GetUserPermissionsService;
use App\Http\Controllers\Api\Client\ClientApiController;
use App\Http\Requests\Api\Client\Servers\GetServerRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server', weight: 0)]
class ServerController extends ClientApiController
{
/**
@ -19,6 +21,8 @@ class ServerController extends ClientApiController
}
/**
* View server
*
* Transform an individual server into a response that can be consumed by a
* client using the API.
*/

8
app/Http/Controllers/Api/Client/Servers/SettingsController.php
View File

@ -9,10 +9,12 @@ use App\Http\Requests\Api\Client\Servers\Settings\RenameServerRequest;
use App\Http\Requests\Api\Client\Servers\Settings\SetDockerImageRequest;
use App\Models\Server;
use App\Services\Servers\ReinstallServerService;
use Dedoc\Scramble\Attributes\Group;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
#[Group('Server - Settings')]
class SettingsController extends ClientApiController
{
/**
@ -25,6 +27,8 @@ class SettingsController extends ClientApiController
}
/**
* Rename
*
* Renames a server.
*/
public function rename(RenameServerRequest $request, Server $server): JsonResponse
@ -56,6 +60,8 @@ class SettingsController extends ClientApiController
}
/**
* Reinstall
*
* Reinstalls the server on the daemon.
*
* @throws \Throwable
@ -70,6 +76,8 @@ class SettingsController extends ClientApiController
}
/**
* Change docker image
*
* Changes the Docker image in use by the server.
*
* @throws \Throwable

6
app/Http/Controllers/Api/Client/Servers/StartupController.php
View File

@ -11,7 +11,9 @@ use App\Http\Controllers\Api\Client\ClientApiController;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use App\Http\Requests\Api\Client\Servers\Startup\GetStartupRequest;
use App\Http\Requests\Api\Client\Servers\Startup\UpdateStartupVariableRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Startup')]
class StartupController extends ClientApiController
{
/**
@ -24,6 +26,8 @@ class StartupController extends ClientApiController
}
/**
* List startup variables
*
* Returns the startup information for the server including all the variables.
*/
public function index(GetStartupRequest $request, Server $server): array
@ -43,6 +47,8 @@ class StartupController extends ClientApiController
}
/**
* Update startup variable
*
* Updates a single variable for a server.
*
* @throws \Illuminate\Validation\ValidationException

12
app/Http/Controllers/Api/Client/Servers/SubuserController.php
View File

@ -17,7 +17,9 @@ use App\Http\Requests\Api\Client\Servers\Subusers\GetSubuserRequest;
use App\Http\Requests\Api\Client\Servers\Subusers\StoreSubuserRequest;
use App\Http\Requests\Api\Client\Servers\Subusers\DeleteSubuserRequest;
use App\Http\Requests\Api\Client\Servers\Subusers\UpdateSubuserRequest;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Subuser')]
class SubuserController extends ClientApiController
{
/**
@ -32,6 +34,8 @@ class SubuserController extends ClientApiController
}
/**
* List subusers
*
* Return the users associated with this server instance.
*/
public function index(GetSubuserRequest $request, Server $server): array
@ -42,6 +46,8 @@ class SubuserController extends ClientApiController
}
/**
* View subusers
*
* Returns a single subuser associated with this server instance.
*/
public function view(GetSubuserRequest $request, Server $server, User $user): array
@ -54,6 +60,8 @@ class SubuserController extends ClientApiController
}
/**
* Create subuser
*
* Create a new subuser for the given server.
*
* @throws \App\Exceptions\Model\DataValidationException
@ -80,6 +88,8 @@ class SubuserController extends ClientApiController
}
/**
* Update subuser
*
* Update a given subuser in the system for the server.
*
* @throws \App\Exceptions\Model\DataValidationException
@ -97,6 +107,8 @@ class SubuserController extends ClientApiController
}
/**
* Delete subuser
*
* Removes a subusers from a server's assignment.
*/
public function delete(DeleteSubuserRequest $request, Server $server, User $user): JsonResponse

4
app/Http/Controllers/Api/Client/Servers/WebsocketController.php
View File

@ -11,7 +11,9 @@ use App\Exceptions\Http\HttpForbiddenException;
use App\Http\Requests\Api\Client\ClientApiRequest;
use App\Services\Servers\GetUserPermissionsService;
use App\Http\Controllers\Api\Client\ClientApiController;
use Dedoc\Scramble\Attributes\Group;
#[Group('Server - Websocket')]
class WebsocketController extends ClientApiController
{
/**
@ -25,6 +27,8 @@ class WebsocketController extends ClientApiController
}
/**
* Get websocket token
*
* Generates a one-time token that is sent along in every websocket call to the Daemon.
* This is a signed JWT that the Daemon then uses to verify the user's identity, and
* allows us to continually renew this token and avoid users maintaining sessions wrongly,

6
app/Http/Controllers/Api/Client/TwoFactorController.php
View File

@ -26,6 +26,8 @@ class TwoFactorController extends ClientApiController
}
/**
* Setup 2fa
*
* Returns two-factor token credentials that allow a user to configure
* it on their account. If two-factor is already enabled this endpoint
* will return a 400 error.
@ -44,6 +46,8 @@ class TwoFactorController extends ClientApiController
}
/**
* Enable 2fa
*
* Updates a user's account to have two-factor enabled.
*
* @throws \Throwable
@ -74,6 +78,8 @@ class TwoFactorController extends ClientApiController
}
/**
* Disable 2fa
*
* Disables two-factor authentication on an account if the password provided
* is valid.
*

7
app/Providers/AppServiceProvider.php
View File

@ -79,11 +79,11 @@ class AppServiceProvider extends ServiceProvider
Sanctum::usePersonalAccessTokenModel(ApiKey::class);
$bearerTokens = fn (OpenApi $openApi) => $openApi->secure(SecurityScheme::http('bearer'));
Gate::define('viewApiDocs', fn () => true);
Scramble::registerApi('application', ['api_path' => 'api/application', 'info' => ['version' => '1.0']]);
$bearerTokens = fn (OpenApi $openApi) => $openApi->secure(SecurityScheme::http('bearer'));
Scramble::registerApi('application', ['api_path' => 'api/application', 'info' => ['version' => '1.0']])->afterOpenApiGenerated($bearerTokens);
Scramble::registerApi('client', ['api_path' => 'api/client', 'info' => ['version' => '1.0']])->afterOpenApiGenerated($bearerTokens);
Scramble::registerApi('remote', ['api_path' => 'api/remote', 'info' => ['version' => '1.0']])->afterOpenApiGenerated($bearerTokens);
// Default OAuth providers included with Socialite
CommonProvider::register($app, 'facebook', null, 'tabler-brand-facebook-f', '#1877f2');
@ -164,7 +164,6 @@ class AppServiceProvider extends ServiceProvider
*/
public function register(): void
{
Scramble::extendOpenApi(fn (OpenApi $openApi) => $openApi->secure(SecurityScheme::http('bearer')));
Scramble::ignoreDefaultRoutes();
}
}

4
composer.json
View File

@ -13,7 +13,7 @@
"calebporzio/sushi": "^2.5",
"chillerlan/php-qrcode": "^5.0.2",
"coderflex/filament-turnstile": "^2.2",
"dedoc/scramble": "^0.10.0",
"dedoc/scramble": "^0.12.10",
"doctrine/dbal": "~3.6.0",
"filament/filament": "^3.2",
"guzzlehttp/guzzle": "^7.8.1",
@ -96,4 +96,4 @@
},
"minimum-stability": "stable",
"prefer-stable": true
}
}

30
composer.lock generated
View File

@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "d19bcea154a71f70e16c50cf517db560",
"content-hash": "bb85f026a4ef019989d0cf14be8dc8d9",
"packages": [
{
"name": "abdelhamiderrahmouni/filament-monaco-editor",
@ -1057,32 +1057,34 @@
},
{
"name": "dedoc/scramble",
"version": "v0.10.13",
"version": "v0.12.10",
"source": {
"type": "git",
"url": "https://github.com/dedoc/scramble.git",
"reference": "d8c3ed9c69fe6c0900f22ec0c7520b9b579d9ec3"
"reference": "996dc8db3e09e7f893d4883dfdfa8f2839fee531"
},
"dist": {
"type": "zip",
"url": "https://api.github.com/repos/dedoc/scramble/zipball/d8c3ed9c69fe6c0900f22ec0c7520b9b579d9ec3",
"reference": "d8c3ed9c69fe6c0900f22ec0c7520b9b579d9ec3",
"url": "https://api.github.com/repos/dedoc/scramble/zipball/996dc8db3e09e7f893d4883dfdfa8f2839fee531",
"reference": "996dc8db3e09e7f893d4883dfdfa8f2839fee531",
"shasum": ""
},
"require": {
"illuminate/contracts": "^10.0|^11.0",
"illuminate/contracts": "^10.0|^11.0|^12.0",
"myclabs/deep-copy": "^1.12",
"nikic/php-parser": "^5.0",
"php": "^8.1",
"phpstan/phpdoc-parser": "^1.0",
"phpstan/phpdoc-parser": "^1.0|^2.0",
"spatie/laravel-package-tools": "^1.9.2"
},
"require-dev": {
"laravel/pint": "^v1.1.0",
"nunomaduro/collision": "^7.0|^8.0",
"orchestra/testbench": "^8.0|^9.0",
"pestphp/pest": "^2.34",
"pestphp/pest-plugin-laravel": "^2.3",
"phpunit/phpunit": "^10.5",
"orchestra/testbench": "^8.0|^9.0|^10.0",
"pestphp/pest": "^2.34|^3.7",
"pestphp/pest-plugin-laravel": "^2.3|^3.1",
"phpunit/phpunit": "^10.5|^11.5.3",
"spatie/laravel-permission": "^6.10",
"spatie/pest-plugin-snapshots": "^2.1"
},
"type": "library",
@ -1119,7 +1121,7 @@
],
"support": {
"issues": "https://github.com/dedoc/scramble/issues",
"source": "https://github.com/dedoc/scramble/tree/v0.10.13"
"source": "https://github.com/dedoc/scramble/tree/v0.12.10"
},
"funding": [
{
@ -1127,7 +1129,7 @@
"type": "github"
}
],
"time": "2024-06-05T17:01:46+00:00"
"time": "2025-02-24T20:12:29+00:00"
},
{
"name": "dflydev/dot-access-data",
@ -14711,4 +14713,4 @@
},
"platform-dev": {},
"plugin-api-version": "2.6.0"
}
}

31
resources/views/docs/api-index.blade.php Normal file
View File

@ -0,0 +1,31 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>API Documentation</title>
@vite('resources/css/app.css')
</head>
<body class="bg-gray-100 min-h-screen flex items-center justify-center">
<div class="bg-white shadow-lg rounded-lg py-8 px-8 max-w-md w-full text-center">
<h2 class="text-xl font-bold text-gray-800 mb-4">API Documentation</h2>
<div class="mb-2">
<a href="/docs/api/application" class="inline-flex items-center">
<span class="mr-2">📘</span> <span style="color: #2563EB;">Application API</span>
</a>
</div>
<div class="mb-4">
<a href="/docs/api/client" class="inline-flex items-center">
<span class="mr-2">📗</span> <span style="color: #10B981;">Client API</span>
</a>
</div>
<div class="text-sm mt-4 flex items-center justify-center">
<span class="text-yellow-500 mr-2">⚠️</span>
<span style="color: #EF4444;">Note: You need to be logged in to view the API docs!</span>
</div>
</div>
</body>
</html>

72
resources/views/vendor/scramble/docs.blade.php vendored Normal file
View File

@ -0,0 +1,72 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<title>{{ $config->get('ui.title', config('app.name') . ' - API Docs') }}</title>
<script src="https://unpkg.com/@stoplight/elements@8.3.4/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements@8.3.4/styles.min.css">
<script>
const theme = localStorage.getItem('theme') === 'system'
? (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
: localStorage.getItem('theme') ?? 'dark';
document.documentElement.setAttribute('data-theme', theme);
const originalFetch = window.fetch;
// intercept TryIt requests and add the XSRF-TOKEN header,
// which is necessary for Sanctum cookie-based authentication to work correctly
window.fetch = (url, options) => {
const CSRF_TOKEN_COOKIE_KEY = "XSRF-TOKEN";
const CSRF_TOKEN_HEADER_KEY = "X-XSRF-TOKEN";
const getCookieValue = (key) => {
const cookie = document.cookie.split(';').find((cookie) => cookie.trim().startsWith(key));
return cookie?.split("=")[1];
};
const updateFetchHeaders = (
headers,
headerKey,
headerValue,
) => {
if (headers instanceof Headers) {
headers.set(headerKey, headerValue);
} else if (Array.isArray(headers)) {
headers.push([headerKey, headerValue]);
} else if (headers) {
headers[headerKey] = headerValue;
}
};
const csrfToken = getCookieValue(CSRF_TOKEN_COOKIE_KEY);
if (csrfToken) {
const { headers = new Headers() } = options || {};
updateFetchHeaders(headers, CSRF_TOKEN_HEADER_KEY, decodeURIComponent(csrfToken));
return originalFetch(url, {
...options,
headers,
});
}
return originalFetch(url, options);
};
</script>
</head>
<body style="height: 100vh; overflow-y: hidden">
<elements-api
id="docs"
tryItCredentialsPolicy="{{ $config->get('ui.try_it_credentials_policy', 'include') }}"
router="hash"
@if($config->get('ui.hide_try_it')) hideTryIt="true" @endif
logo="{{ $config->get('ui.logo') }}"
/>
<script>
(async () => {
const docs = document.getElementById('docs');
docs.apiDescriptionDocument = @json($spec);
})();
</script>
</body>
</html>

9
routes/docs.php
View File

@ -10,12 +10,5 @@ Route::group(['prefix' => 'api'], function () {
Scramble::registerUiRoute(path: 'client', api: 'client');
Scramble::registerJsonSpecificationRoute(path: 'client.json', api: 'client');
Scramble::registerUiRoute(path: 'remote', api: 'remote');
Scramble::registerJsonSpecificationRoute(path: 'remote.json', api: 'remote');
Route::get('', fn () => '
<li><a href="/docs/api/application">Application API for Admins</a></li>
<li><a href="/docs/api/client">Client API for Users</a></li>
<li><a href="/docs/api/remote">Daemon API for Wings</a></li>
');
Route::view('', 'docs.api-index');
});