Spectacular Laravel Package

Product Decisions This Supports

• API contract quality as a shipped product surface. Spectacular sits on top of dedoc/scramble and lets us shape the generated OpenAPI spec — discriminators for polymorphic OneOf responses, custom InfoObject metadata, and control over how nested filter parameters are flattened. That means the decision "do we publish a spec at all?" becomes "how accurate is the spec our SDKs and partners consume?"
• Build vs. buy for spec post-processing. The alternative is hand-maintaining OpenAPI YAML or writing our own Scramble post-processors. Version 0.30.0 is a useful signal on both sides: the package is actively tracking Scramble internals (fixes landed within days of Scramble 0.13.48), but it also inherits Scramble's churn. Lean toward buying if our spec needs are "standard REST + a few polymorphic payloads"; lean toward building if we need heavy, bespoke schema surgery.
• Client-facing documentation accuracy for nested filters. The headline feature — respecting flatten_deep_query_parameters for filters — directly affects whether generated docs and client SDKs describe deeply nested filter params (e.g. filter[author][name]) correctly. If we expose nested filtering to external consumers, this is a correctness fix for the developer experience, not a cosmetic one.
• Upgrade planning and maintenance budget. This is a breaking release (requires dedoc/scramble ^0.13.48, changed OneOf::setDiscriminator() signature to accept Scramble's Discriminator, removed Spectacular's own InfoObject). Treat it as a roadmap item with engineering cost, not a routine composer update. Any consumer code referencing Spectacular's InfoObject or calling setDiscriminator() with the old type must be migrated in the same change.
• Dependency posture as a risk input. Being pre-1.0 at 0.30.0 and coupled to Scramble's serialisation internals means breaking changes are expected, not exceptional. That should be priced into any commitment to publish a stable public spec.

When to Consider This Package

Adopt when:

• We already use dedoc/scramble and need schema refinements Scramble does not provide out of the box — particularly discriminated OneOf unions (polymorphic API resources) and custom InfoObject metadata for a published spec.
• We expose nested/deep query filters and need the generated spec to mirror Scramble's flatten_deep_query_parameters setting, so client generators produce usable parameter names.
• Our spec is a contract with external consumers or drives SDK generation, so documentation drift has real cost.
• We can pin to an exact minor version and absorb periodic migration work — and we are willing to upgrade Scramble and Spectacular together as a coupled pair.

Look elsewhere when:

• Scramble's native output already covers our needs; adding a post-processor layer buys complexity without changing the consumer experience.
• We need a genuinely stable, semver-guaranteed dependency (this is 0.x with declared breaking changes).
• We are on a Scramble version below 0.13.48 and cannot upgrade — 0.30.0 is not available to us.
• Our spec is generated from a hand-authored design-first source (e.g. an OpenAPI file driving the implementation), making a code-first generator the wrong direction.
• The team cannot own the migration work implied by setDiscriminator() signature changes and InfoObject removal.

How to Pitch It (Stakeholders)

For executives: This is a small, focused library that improves the accuracy of the API documentation we hand to partners and use to generate client SDKs. The new 0.30.0 release fixes a real correctness gap — nested filter parameters now appear in the spec the way our API actually behaves — which reduces integration support load and prevents client-side bugs. The trade-off is that it is a pre-1.0 dependency with an explicit breaking change in this release, so adopting it means committing a modest, recurring maintenance budget to keep it in lockstep with its upstream library. Recommendation: adopt if external API documentation accuracy is a priority; budget one engineering migration per significant upstream bump.

For engineering: 0.30.0 is breaking. Requirements: dedoc/scramble ^0.13.48; OneOf::setDiscriminator() now takes Scramble's Discriminator type; Spectacular's own InfoObject class is removed. Audit the codebase for both before upgrading, and upgrade Scramble and Spectacular as a single change set — do not bump one without the other. The functional win is that flatten_deep_query_parameters is now honoured for filter parameters, so generated specs match runtime query semantics for nested filters. Because this package patches Scramble's serialisation internals, pin to an exact minor version and treat each release as a review item rather than auto-merging dependency updates.