Download the PHP package botnetdobbs/laravel-luminous without Composer

Luminous

Generate OpenAPI 3.2.0 docs from PHP 8 Attributes on your Laravel controllers.

No YAML files to maintain. No docblocks to parse. Put a few attributes on your controllers, let your FormRequest rules() define the request body, document your API Resources with a single static schema() method, and Luminous builds the full spec automatically.

Request bodies follow your FormRequest rules(), so they stay up to date with validation. Response docs use a separate schema() method (or #[ApiProperty]). Keep schema() next to toArray() so the docs still match what you return.

Docs: botnet-dobbs.github.io/laravel-luminous

Requirements

• PHP 8.2+

Installation

Publish the config file:

Your API docs are live at /docs.

Local vs production

By default, docs work right away on your machine: no login, UI turned on. That is on purpose so you can install the package and open /docs immediately.

On a production server, protect the docs or turn them off:

Also build the cache when you deploy and limit which routes get documented with include_routes. Details:

• Deployment: middleware, cache, generate, export
• Security: documenting auth schemes and scopes in the spec

Quick Look

The controller

Tag the controller and secure it. Every method inside inherits both automatically.

Luminous detects CreatePaymentRequest from the type hint and reads its rules() to build the request body schema. It detects Payment as a route model bound parameter and maps it to the {payment} segment automatically. No wiring required.

The FormRequest

rules() defines the schema. hints() adds descriptions and examples for fields that need more context. You only need hints() when the field name alone is not enough.

The API Resource

Add #[ApiShape] and write a schema() method. Luminous calls it when building the response schema.

That is the whole picture. The individual docs below go into every detail.

Documentation

Full docs: botnet-dobbs.github.io/laravel-luminous

• Configuration
• Documenting Controllers
• Documenting Form Requests
• Documenting API Resources
• The Shape Builder
• Security
• CLI Commands and Deployment

Attribute Reference

Common Questions

Do I need to annotate every controller method?

No. Every route appears in the spec. Unannotated routes get an auto-generated summary from the controller and method name. Annotations make things accurate and readable but are never required.

What happens if I forget #[ApiResponse]?

Luminous adds a default 500 Internal Server Error response. Other responses are assumed to return a generic object. Add #[ApiResponse] to make the response schemas accurate.

My FormRequest has constructor dependencies. Will rules() work?

For most cases yes. Luminous instantiates the request without calling the constructor. If your rules() calls $this->user() or reads injected services, those calls fail silently and Luminous returns a bare schema. Restructure those rules to avoid request-time dependencies, or use #[ApiShape] to provide the schema explicitly.

Can I use a plain PHP class or DTO with #[ApiResponse]?

Yes. #[ApiResponse] accepts any class name. If the class has #[ApiShape] with a schema() method, or has #[ApiProperty] on its public properties, Luminous extracts the schema from it just like it would from a JsonResource.

Can I check the exported file, or build an SDK from it?

Yes. Export with luminous:export, then use normal OpenAPI tools. Redocly or Spectral can check the file. openapi-generator or Fern can build a client library. See Using the exported spec.

Credits

• Lazarus Odhiambo
• All Contributors

License

The MIT License (MIT). See LICENSE for details.