Filament Openapi Docs Laravel Package

Technical Evaluation

Architecture fit. Filament OpenAPI Docs is a Filament panel plugin that surfaces Scramble-generated OpenAPI specifications as rendered documentation inside the admin panel. v1.0.4 adds a version-resolution layer on top of the existing single-generator path: versions() drives an in-page selector, version() produces a dedicated page bound to one API version, and named Scramble APIs are auto-discovered. Architecturally this is an additive, presentation-layer change — no new infrastructure, no new runtime dependency class, no schema or persistence changes. The stated preservation of legacy single-generator behavior means the default code path is unchanged, which keeps the plugin's footprint small for teams that never opt into multi-version.

Integration feasibility. Integration remains a Composer install plus plugin registration in a Filament panel provider; the release's npm run build step indicates front-end assets are compiled and shipped/published rather than built by the consumer. The multi-instance fix ("separate plugin instances without Filament page configuration conflicts") is the most operationally meaningful item: it removes a known class of panel-provider collisions in setups with multiple docs surfaces (e.g., public vs. internal API docs, or per-team panels). That is a low-effort, high-clarity win and is the strongest reason to take the upgrade even without needing versioning.

Technical risk. Low-to-moderate. No breaking changes, deprecations, or removals are declared, and 72 passing tests plus a formatter pass are positive but self-reported signals — they evidence the author's workflow, not a published CI matrix. The real risk surface is the new URL and configuration surface: dedicated per-version pages introduce additional routes whose slugs, naming, and middleware must be verified against existing panel routes; version labels now embed both OpenAPI version and API path, which changes rendered UI text and could disturb visual/snapshot assertions or user-facing links. Because front-end assets changed, consumers who publish assets may hold stale builds after upgrade. Version discovery is automatic for named Scramble APIs, which is convenient but reduces explicitness — teams should confirm what happens with unnamed or partially configured generators.

Key questions.

• What is the supported version matrix (PHP, Laravel, Filament major, Scramble major)? The release notes are silent, and Filament's v3→v4 transition makes this decisive.
• How exactly are "named Scramble APIs" discovered — config key, service container tag, or filesystem scan — and what is the failure mode when zero or one named API exists?
• Do generated per-version routes inherit the panel's auth/middleware stack by default, or must authorization be attached explicitly? Docs pages can leak full API surface if exposed.
• Are published assets required to be re-published on upgrade, and is that idempotent?
• What is the caching story for large specifications rendered across N versions?
• Is there CI beyond the author's local Pest/Pint/build run?

Integration Approach

Stack fit. Targets Laravel applications already running Filament with Scramble as the OpenAPI generator. If Scramble is already producing specs for CI or client SDKs, this plugin is a pure presentation layer over artifacts you already own — a favourable ratio of value to new surface area. If Scramble is not yet adopted, this release is not the reason to adopt it; sequence the generator first.

Migration path. Patch-level upgrade (1.0.x → 1.0.4) with explicit "no breaking changes" and no deprecations or removals. Existing single-generator configurations should continue rendering unchanged; versions() and version() are opt-in. Recommended path: upgrade the constraint, republish compiled assets, smoke-test the existing docs page, then introduce versioning in a non-production panel before promoting. Avoid combining this bump with a Filament or Scramble major upgrade in the same change — the version-discovery behavior depends on generator naming, and co-mingling changes makes regressions hard to attribute.

Compatibility. The multi-instance coexistence fix is the compatibility item to validate: teams running more than one docs plugin in a panel should confirm both pages register, both render, and neither hijacks the other's configuration. Legacy single-generator configurations are the other must-verify path, since "preserved" behavior is asserted rather than proven by a published compatibility statement.

Sequencing.

1. Confirm PHP/Laravel/Filament/Scramble versions against the package's declared constraints.
2. Upgrade in a sandbox panel; republish assets; verify the legacy single-generator page renders identically.
3. Add a second plugin instance and confirm no page-configuration conflict.
4. Introduce versions() with two real APIs; verify the selector, labels, and each version() route resolves and is authorized.
5. Review route table diff and middleware in staging; then production.
6. Update internal docs/runbook with the new config keys and the asset-republish step.

Operational Impact

Maintenance. Small, actively released package with a visible test and build habit; the cadence (patch releases with tests and changelog discipline) suggests a maintainer who responds to issues. The dependency risk is transitive and concentrated: the plugin's useful life is bounded by Scramble's and Filament's major-version trajectories, so pin loosely but review on every Filament major. Budget a recurring small task — re-verify version discovery and republish assets — rather than treating this as install-and-forget.

Support. Audience is internal developers and API consumers reading docs, so blast radius from a rendering bug is low; blast radius from an authorization bug is not. Treat the docs pages as an information-disclosure surface: confirm they sit behind the same auth as the panel and that per-version routes do not bypass it. Support load is likely to concentrate in two areas — "a version is missing from the selector" (discovery/naming) and "the page looks stale" (unpublished assets).

Scaling. Rendering is static per request with no write path, so compute cost is dominated by specification size and version count. Multiple versions multiply both routes and in-memory parse cost; a panel exposing many large specs will show slower page loads and heavier memory per request. If version count grows past a handful or specs exceed a few MB, expect to need response caching or a build-time artifact rather than request-time generation. The in-page selector also means one page may load metadata for all versions — worth measuring, not assuming.

Failure modes.

• Zero or ambiguously named Scramble APIs → empty or partial version selector, silent rather than loud.
• Route slug or name collisions between per-version pages and existing panel routes.
• Stale published assets after upgrade producing a mismatched sidebar/labels UI.
• Authorization not inherited on newly generated version routes → unintended exposure of full API surface.
• Configuration conflict when multiple plugin instances share a panel (the exact case this release claims to fix — verify, don't trust).
• Large or malformed OpenAPI documents degrading or breaking render for all versions on a shared page.

Ramp-up. For a Laravel developer already fluent in Filament panel providers, adoption is measured in hours: one plugin registration, one config block, one asset publish. The learning curve is almost entirely in Scramble's generator naming and configuration, not in this package. TPM-level ramp-up is lighter still — the decisions to make are the version-matrix check, the authorization review, and the asset-republish step in the runbook. Recommend a half-day spike covering the two-plugin and two-version scenarios before committing to a rollout.