# Swagger / OpenAPI on cPanel

The backend uses **L5-Swagger 11.x** to host Swagger UI and the existing `docs/OPENAPI.yaml` as the canonical API specification.

## URLs

After deployment:

- Swagger UI: `https://YOUR-API-DOMAIN/api/documentation`
- The UI reads the generated document from `storage/api-docs/api-docs.json` through L5-Swagger.

## cPanel deployment

### 1. Point the domain/subdomain to Laravel `public`

Preferred cPanel document root:

```text
/home/CPANEL_USER/bioluminux-api/public
```

The package includes `public/.htaccess` for Apache/LiteSpeed rewrite handling.

### 2. Configure `.env`

At minimum:

```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://api.example.com

SWAGGER_ENABLED=true
SWAGGER_SERVER_URL=https://api.example.com
L5_SWAGGER_GENERATE_ALWAYS=false
L5_SWAGGER_USE_ABSOLUTE_PATH=true
L5_SWAGGER_OPEN_API_SPEC_VERSION=3.1.0
```

`SWAGGER_SERVER_URL` is optional. When empty, `php artisan swagger:sync` uses `APP_URL`.

### 3. Install production dependencies

From cPanel Terminal/SSH in the Laravel project root:

```bash
composer install --no-dev --prefer-dist --optimize-autoloader
```

L5-Swagger is a production dependency so Swagger UI remains available with `--no-dev`.

### 4. Build the Swagger document for this domain

```bash
php artisan swagger:sync
```

This reads `docs/OPENAPI.yaml`, replaces the OpenAPI `servers` entry with the deployed API URL, and writes:

```text
storage/api-docs/api-docs.json
```

You can override the server for one build:

```bash
php artisan swagger:sync --server=https://api.example.com
```

### 5. Complete Laravel deployment

```bash
php artisan migrate --force
php artisan storage:link
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

Ensure these directories are writable by the cPanel PHP user:

```text
storage/
bootstrap/cache/
```

Typical permissions are directories `755`/`775` depending on the host. Do not use `777` unless the hosting provider explicitly requires it.

## Updating the docs later

Edit `docs/OPENAPI.yaml`, then run:

```bash
php artisan swagger:sync
php artisan optimize:clear
```

You do **not** need `php artisan l5-swagger:generate` for this project because the canonical specification is maintained as OpenAPI YAML rather than duplicated as PHP controller attributes.

## Production access control

To turn Swagger off without uninstalling it:

```env
SWAGGER_ENABLED=false
```

Then run:

```bash
php artisan config:cache
```

The Swagger UI, documentation JSON route, assets, and OAuth callback will respond as not found while disabled.

## Testing authenticated admin endpoints in Swagger

The admin API uses Laravel Sanctum stateful session authentication and CSRF protection. Keep Swagger UI on the **same API origin**. The Swagger UI route runs through Laravel's `web` middleware, keeps cookies enabled, and its request interceptor sends the Laravel CSRF header. This allows the documented `/api/admin/login` flow to establish the same session used by subsequent protected calls.

For the normal Next.js application, continue to use the established flow:

1. `GET /sanctum/csrf-cookie`
2. `POST /api/admin/login`
3. authenticated `/api/admin/*` requests with credentials/cookies.

## If `/api/documentation` returns 404

Check:

```env
SWAGGER_ENABLED=true
```

Then:

```bash
php artisan optimize:clear
php artisan route:list | grep documentation
```

## If Swagger loads but shows "Failed to load API definition"

Run:

```bash
mkdir -p storage/api-docs
php artisan swagger:sync
php artisan optimize:clear
```

Then confirm `storage/api-docs/api-docs.json` exists and that `storage` is readable by PHP.

## If Swagger assets fail on HTTPS

Set:

```env
APP_URL=https://api.example.com
L5_SWAGGER_USE_ABSOLUTE_PATH=true
```

and clear cached config:

```bash
php artisan optimize:clear
php artisan config:cache
```

Also make sure cPanel/Cloudflare/proxy HTTPS forwarding is configured correctly so Laravel detects the request as HTTPS.