Filament Api Docs Builder Laravel Package

Getting Started

Treat this as a young, unproven package (0 stars, 0 dependents), so the first job is reconnaissance rather than integration. Before writing any app code:

1. Read the repo top-to-bottom first. Open README.md, composer.json, and src/. You are looking for three things: the supported Filament major version (filament/filament constraint), the Laravel/PHP floor, and whether the package ships a ServiceProvider plus a Filament Plugin class. If the README does not state a Filament version, assume it targets whatever was current when it was last committed and verify against your composer.lock.
2. Install into a scratch branch, not main.

   composer require zpmlabs/filament-api-docs-builder
   

   Pin it ("zpmlabs/filament-api-docs-builder": "dev-main#<commit>" or an exact tag) so a force-push upstream cannot silently change your admin panel.
3. Publish and diff. Run php artisan vendor:publish --provider="Zpmlabs\\FilamentApiDocsBuilder\\FilamentApiDocsBuilderServiceProvider" (confirm the exact provider FQCN from src/) and inspect what lands in config/. Any published config is your contract for behavior — read every key before changing one.
4. Register the plugin in your panel provider, which is the standard Filament entry point:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(ApiDocsBuilderPlugin::make());
   }
   

   Namespace and make() signature must come from src/ — do not assume.
5. First use case: point it at a single, low-risk API surface (one internal resource or one small controller group) and view the generated docs page in the admin panel. Success criteria: the page renders, endpoints are listed, and you can click through to a detail view without a 500. Only after that should you consider wiring it to a customer-facing or versioned API.

If any of steps 1–4 fail (no Plugin class, no service provider, missing Filament constraint), stop — the package is not production-ready and the cost of forking will exceed the cost of writing a simple docs resource yourself.

Implementation Patterns

Because the package is undocumented in the wild, patterns below are the ones that generalize to Filament doc-builder plugins. Verify each against src/ before committing to it.

Panel-scoped registration. Register the plugin only on the panel that should expose docs (e.g. an AdminPanelProvider), never on a public-facing panel. Filament panels are cheap to add; a second DocsPanelProvider gated behind canAccessPanel() is the cleanest way to keep API docs off the customer app.

Authorization first, rendering second. Whether the plugin exposes a Resource, Page, or custom View, wire access control in the same PR that installs it:

public static function canViewAny(): bool
{
    return auth()->user()?->can('viewApiDocs') ?? false;
}

Do not rely on panel-level authGuard() alone if the docs can leak internal endpoint names, request schemas, or example payloads.

Source-of-truth discipline. Decide up front whether docs are derived (scanned from routes/controllers/FormRequests) or authored (stored in DB/JSON and edited in Filament). Derived docs rot silently when routes change; authored docs rot when nobody updates them. For a small team, authored-in-DB with a version column is usually the better bet. If the package scans routes, add a CI check that fails when generated output differs from committed output.

Grouping and navigation. Filament's navigation model (groups, sort, icons, badges) is the main lever you have over usability. Model your API surface as nav groups per domain (Billing, Auth, Webhooks) rather than one flat list. If the plugin exposes a navigationGroup() or getNavigationItems(), override it in your own subclass instead of editing vendor code.

Localization and examples. Keep example request/response payloads in lang/ or a dedicated docs/ directory keyed by endpoint slug, so a technical writer can edit them without touching PHP. This is the single highest-leverage customization for day-to-day usefulness.

Export for consumers. Developers consuming the API do not want to log into your admin panel. Add an artisan command or scheduled job that renders the same docs to static HTML/OpenAPI and publishes to a docs host or repo. This turns an admin-only tool into something the whole org uses.

Gotchas and Tips

The star count is the headline risk. Zero stars, zero dependents means zero external bug reports. Expect to be the first person to hit edge cases, and budget for reading vendor source when something 500s. Fork it under your org and require your fork in composer.json — that gives you a stable URL, a place for patches, and protection against the upstream repo disappearing.

Filament v3 vs v4 breakage. Filament's plugin API, resource base classes, and asset registration changed between majors. A package that compiles against v3 will often install cleanly on v4 (because the constraint is loose) and then fail at runtime with missing methods. Check composer.json for the constraint, and if it is ^3.0 on a v4 app, do not install.

Asset and cache pitfalls. Filament plugins frequently register CSS/JS via FilamentAsset::register(). After install or upgrade:

php artisan filament:assets
php artisan optimize:clear

A blank or unstyled docs page is almost always a missing asset publish or a stale bootstrap/cache. In production, php artisan filament:cache-components must be re-run after any plugin change or the docs pages will 404.

Route scanning surprises. If the package derives endpoints from the router, it will pick up package routes, health checks, and Telescope/Horizon endpoints you never intended to document. Check for an except/only/middleware filter in the config and set it explicitly. Also verify behavior under route:cache — reflection-based scanners that read Router::getRoutes() at boot can behave differently when routes are cached.

Authorization is not automatic. Filament resources inherit canViewAny() from policies; custom pages inherit nothing. If the plugin ships a Page, audit it for a canAccess() override. A docs page that renders for any authenticated user is a common and quiet information-disclosure bug.

Debugging checklist when the page is blank or broken:

• php artisan about — confirm the panel and plugin are both booted.
• Check storage/logs/laravel.log for the plugin's namespace in the stack trace; Filament swallows view exceptions into a generic error page in production.
• Set APP_DEBUG=true locally and hit the docs route directly.
• php artisan route:list | grep -i docs — confirm the route is registered at all.

Extension points to prefer. Subclass the plugin/resource rather than editing vendor/. Override getNavigationLabel(), getNavigationGroup(), canViewAny(), and any getXxxSchema()/form(Schema $schema) method in your own class. Re-publishing vendor views (vendor:publish --tag=filament-api-docs-builder-views) is acceptable for one-off layout changes but will silently miss upstream fixes — note the publish date in a comment.

Have an exit plan. Given the maturity level, write the integration so it is replaceable in an afternoon: keep docs content in your own docs/ directory or DB table, keep the plugin registration to a single line in the panel provider, and avoid storing business logic in plugin callbacks. If the package stalls, swapping it for a hand-rolled Filament resource over the same data should be a small diff, not a rewrite.