CLI Commands and Deployment

---

Where your docs are served

Once installed, Luminous registers three routes under the path you set in config (default: docs):

URL	What you get
/docs	Swagger UI, the interactive browser
/docs/openapi.json	The raw OpenAPI 3.2 spec as JSON
/docs/openapi.yaml	The raw OpenAPI 3.2 spec as YAML (requires symfony/yaml)

Change the path with LUMINOUS_PATH=api-docs in your .env and the routes move to /api-docs, /api-docs/openapi.json, and /api-docs/openapi.yaml.

---

CLI Commands

Generate and cache the spec

php artisan luminous:generate

This reflects over your routes and classes, generates the OpenAPI spec, stores it in the cache, and prints a summary:

Generating OpenAPI 3.2 spec...
Done in 142ms.
+-----------------------+-------+
| Metric                | Count |
+-----------------------+-------+
| Paths                 |    34 |
| Schemas in components |    21 |
+-----------------------+-------+
Spec: http://localhost/docs/openapi.json

Force a fresh generation even if the cache is already warm:

php artisan luminous:generate --force

Run a basic structural check after generating:

php artisan luminous:generate --validate

The --validate flag only does a few simple checks:

• the openapi field is set
• info.title and info.version are set
• there is at least one path
• every HTTP operation has a responses object

It does not look for duplicate operationId values, broken $ref links, or other full OpenAPI problems. For a full check, use a real OpenAPI linter (see Check the spec (lint)).

---

Export the spec to a file

Export as JSON:

php artisan luminous:export --format=json --output=openapi.json

Export as YAML (requires the symfony/yaml package):

composer require symfony/yaml
php artisan luminous:export --format=yaml --output=openapi.yaml

Print to stdout and pipe to a validator:

php artisan luminous:export --format=json | npx @redocly/cli lint -

Skip the cache and generate fresh output:

php artisan luminous:export --format=json --no-cache --output=openapi.json

Pretty-print the JSON output:

php artisan luminous:export --format=json --pretty --output=openapi.json

---

Deployment

Caching in production

Always enable the cache in production. The spec is generated through reflection and route inspection. It is fast enough for development, but caching means production requests never pay for reflection at all.

The cache key is your LUMINOUS_CACHE_KEY prefix plus a short hash of package version and config. After a package upgrade or config change, the next request builds a new entry instead of serving an old one. Old entries expire on their own when their TTL runs out.

LUMINOUS_CACHE=true
LUMINOUS_CACHE_TTL=3600
LUMINOUS_CACHE_STORE=redis

Add spec generation to your deploy script so the cache is warm the moment your deploy goes live:

# Run this after composer install and migrations
php artisan luminous:generate --force

---

Restricting access in production

Docs should not be publicly accessible in production. Set middleware to require authentication before anyone can view the spec:

LUMINOUS_MIDDLEWARE=auth:sanctum

You can use any middleware your app already has. List more than one with a pipe (|), not a comma. Commas are used inside some middleware options (like throttle:60,1), so a comma would cut those names in the wrong place:

LUMINOUS_MIDDLEWARE=auth:sanctum|verified
# or with rate limiting:
# LUMINOUS_MIDDLEWARE=auth:sanctum|throttle:60,1

Or hide the docs entirely and distribute the spec as a static file to internal consumers only:

LUMINOUS_ENABLED=false

php artisan luminous:export --format=yaml --output=storage/app/openapi.yaml

---

OpenAPI validation in CI

Add spec validation to your CI pipeline to catch documentation errors before they reach production. This also ensures that new routes and schema changes do not break the spec structure.

# .github/workflows/ci.yml
- name: Validate OpenAPI spec
  run: |
    php artisan luminous:export --format=json --no-cache --output=/tmp/openapi.json
    npx @redocly/cli lint /tmp/openapi.json

You can also use swagger-cli or the Redocly GitHub Action if you prefer.

---

Exporting for third-party tools

Some teams distribute the spec to consumers via Postman, Insomnia, or an internal developer portal. Export the spec to a known location as part of your deployment:

# Export to a storage path that your portal can read
php artisan luminous:export --format=json --output=storage/app/public/openapi.json

# Or commit it to the repo as documentation
php artisan luminous:export --format=yaml --output=docs/openapi.yaml

---

Using the exported spec

Luminous writes a standard OpenAPI 3.2 file, so any OpenAPI tool can read it.

Check the spec (lint)

Tools like Redocly CLI and Spectral check your file against OpenAPI rules (and your own rules, if you add them):

php artisan luminous:export --format=json --no-cache --output=openapi.json
npx @redocly/cli lint openapi.json

This finds missing descriptions, broken $ref links, bad schemas, and other problems before other people use the docs. Use this for a full check. luminous:generate --validate only does the simple checks listed in Generate and cache the spec.

Build an SDK (client library)

Tools like openapi-generator and Fern read your OpenAPI file and create a client library in the language you pick:

php artisan luminous:export --format=json --no-cache --output=openapi.json

npx @openapitools/openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-axios \
  -o ./sdk

That example makes a TypeScript client from your Luminous file. You can do the same for Python, Go, Java, PHP, and other languages those tools support.

These are normal OpenAPI tools. Luminous only needs to write a good spec file.