Download the PHP package eng-mmustafa/canopy without Composer

🌿 Canopy

Beautiful, hierarchical API documentation for Laravel — powered by Scramble.

Scramble generates a great OpenAPI document automatically. Canopy adds what large APIs need: a nested, navigable, branded documentation explorer. Group your endpoints into a tree (Admin → Users → Sessions…), search them instantly, and ship docs that look like your product.

Canopy is a drop-in add-on. It depends on Scramble and does not modify or fork it — it builds on Scramble's public extension points, so you keep upgrading Scramble normally.

Why Canopy?

• Hierarchical groups — unlimited nesting, unlike flat tag lists.
• Zero core changes — pure add-on; your Scramble setup is untouched.
• Your brand — title, logo, accent color, light/dark theme.
• Dark / Light mode toggle — one-click switch with preference saved in localStorage.
• Fast search — filter the whole API tree as you type.
• Automatic grouping — by #[Group] attribute, config rules, route prefix/name, or controller name.
• Bearer token support — add securitySchemes once; TryIt shows an auth input on every endpoint.
• Large app support — serve a pre-exported JSON file instead of generating on every request.

Requirements

Installation

Laravel auto-discovers the service provider. Then open:

Publish the config to customize:

Quick start

Step 1 — Install & visit

Visit /docs/canopy — Canopy auto-generates the tree from your existing Scramble setup.

Step 2 — Add Bearer token support (recommended)

Add this to your AppServiceProvider::boot() so TryIt shows an auth input on every endpoint:

Step 3 — (Large apps) Pre-export the document

For large codebases, generate the spec once instead of on every request:

Then add to .env:

Re-run the export whenever your API changes (e.g. in your CI/CD pipeline).

Grouping

Canopy resolves each endpoint's group in priority order. The first that matches wins:

1. #[Group] attribute (nested with / or >)

2. Config rules

Match conditions: prefix, name, middleware, namespace (all glob-matched).

3. Route prefix / name

Route::prefix('admin/billing') → Admin → Billing. Falls back to the dotted route name (admin.users.index → Admin → Users).

4. Controller name (fallback)

InvoiceController → Invoice. Finally, the configurable fallback group (default General).

Branding

The user can also toggle dark/light mode at any time via the 🌙 button in the sidebar header. Preference is saved in localStorage and overrides the config value.

Publish and customize the view:

Configuration reference

Large applications

On big codebases, generating the OpenAPI document on every web request can be slow or exhaust PHP memory.

Option 1 — Raise the memory limit:

Option 2 (Recommended) — Pre-export the document:

Add the export to your deploy script so docs stay in sync with your code.

How it works

1. Scramble generates the OpenAPI document (unchanged).
2. Canopy maps each documented operation back to its Laravel route.
3. A resolver pipeline assigns each route a (possibly nested) group path.
4. A tree builder assembles the hierarchy.
5. The sidebar renders the tree; Stoplight Elements renders the operation detail.
6. Clicking a sidebar link fires hashchange / popstate events that Stoplight's internal React Router picks up — no page reload.

No x-tree, no patched OpenApi, no forked Scramble — everything happens inside Canopy.

Testing

Changelog

License

MIT © Mohammed Mostafa. Built on top of the excellent Scramble by Roman Lytvynenko.