Filament Openapi Docs Laravel Package

Getting Started

This release (v1.0.4) is purely additive — nothing you have running will break. Start by reading the README section covering versions() and version(), since that is where the new surface area lives.

Minimal steps to get productive:

1. composer update the package (no config changes required to keep existing behaviour).
2. Confirm your Scramble setup still generates specs — the plugin only renders what Scramble exposes.
3. Open your existing docs page in the panel. It should look and behave exactly as before; that is your regression baseline.
4. If you have more than one API surface (e.g. a public /api and an internal /internal-api), register both with Scramble as named APIs, then switch the plugin from the single-generator config to versions([...]).

Where to look first:

• The plugin's config/registration in your PanelProvider — this is where every change in this release is expressed.
• Scramble's own configuration, because "automatic discovery of named Scramble APIs" depends on those APIs actually being named and registered there.
• The package README for the exact shape of versions() / version() arguments and the label format (labels now include the OpenAPI version and the API path).

First use case to try: keep your current single-generator plugin untouched, then add a second plugin instance scoped to one version with version(). That gives you a dedicated, linkable page per API version and validates the "separate plugin instances without page configuration conflicts" fix from this release without touching your existing page.

Implementation Patterns

Legacy single generator (no change). If you document one API, do nothing. Legacy behaviour is explicitly preserved. Treat this as the default and only migrate when you actually have a second version.

In-page selector with versions(). Use this when consumers benefit from switching between API versions on one screen — public API docs where v1 and v2 coexist, or a "latest vs. stable" toggle. One plugin instance, one route, a summary/sidebar selector swaps the rendered spec. Good for discoverability; less good if the versions have wildly different auth or audiences.

Dedicated page per version with version(). Use this when each version needs its own URL, navigation entry, and access rules — e.g. /admin/docs/v1 and /admin/docs/v2, or public docs for one version and an internal-only page for another. Register multiple plugin instances in the same panel, each pinned to one version. This is the pattern that the v1.0.4 instance-isolation fix unlocks; before it, multiple instances in one panel collided on page configuration.

Mixed pattern. Combine both: a versions() page as the general entry point, plus version() pages for the versions you want directly linkable (changelogs, support tickets, Slack pins). Keep the dedicated pages out of navigation (->navigationIcon(null) / hidden nav) if you only want them linkable rather than browsable.

Panel segregation. The most common real-world split is public vs. internal: an unauthenticated or lightly-guarded panel rendering the public spec, and an admin panel rendering internal endpoints. Each panel gets its own plugin instance and its own version config; do not try to share one instance across panels.

Integration tips.

• Drive the versions list from your own config (config('openapi.versions')) rather than hardcoding arrays in the provider, so deploys can toggle versions without a code change.
• Gate access with the panel's canAccessPanel() / the plugin's authorization hook rather than relying on route obscurity — the docs page exposes your entire schema.
• Add a Pest smoke test per registered docs page asserting a 200 and a stable heading. Because labels now embed the OpenAPI version and path, assert on your own page title, not on the generated label string.
• In CI, run php artisan route:list | grep docs after adding instances to catch slug collisions early.

Gotchas and Tips

• Discovery is not magic. "Automatic discovery of named Scramble APIs" only finds APIs that Scramble itself knows about by name. If a generator is registered anonymously or you only ever configured the default, it will not appear in the selector. Name your APIs in Scramble's config first, then wire versions().
• Slug collisions throw. Two plugin instances in the same panel need distinct slugs (and ideally distinct navigation labels/ids). Filament will fail loudly on duplicate routes — that is the symptom to look for when a page 404s or the panel won't boot.
• Clear caches after changing versions. php artisan config:clear && php artisan route:clear (plus optimize:clear in production). Adding a version is a route change; a cached route table will keep serving the old set of docs pages.
• Published views/config from an older version win. The sidebar summary UI changed in this release. If you previously ran vendor:publish, your stale published view will hide the new selector. Republish (or diff the packaged view) before filing a bug that the selector "doesn't appear".
• Assets on upgrade. If the package ships compiled assets, re-run the Filament asset publish step after upgrading, otherwise the updated sidebar UI loads with old CSS/JS.
• Don't assert on label text. Labels now include the OpenAPI version and API path. Tests that snapshot or assert on "v1" style strings will be brittle across future releases; assert on slugs, page titles, or your own navigation labels instead.
• Large specs are slow to render. The selector multiplies the amount of spec content in play. Enable Scramble's caching in production and avoid rendering every version eagerly if one of them is huge.
• Security default. Each new docs page is another unauthenticated-by-default surface. When you add version() pages, explicitly decide who can see them — especially for internal APIs sharing a panel with public ones.
• Extension point. Because instances are now isolated, prefer composing several small plugin instances (one per version, per audience) over one heavily-conditioned instance. It keeps navigation, authorization, and route naming independently controllable.
• No deprecations. Nothing in this release pushes you off the old API. Migrate to versions() opportunistically, one panel at a time, keeping the legacy page live until the new one is verified.