Spectacular Laravel Package

Technical Evaluation

• Architecture fit: bambamboole/spectacular is a Laravel/PHP package that extends dedoc/scramble to generate OpenAPI documentation from Laravel routes, controllers, and validation rules. It fits Laravel API services or monoliths already using Scramble, especially teams treating API contracts as build artifacts for client SDKs, contract tests, or gateway configuration. Version 0.30.0 remains a thin extension layer, so architectural coupling is mainly to Scramble rather than to application runtime code.
• Integration feasibility: Feasible via Composer, but 0.30.0 introduces a hard dependency on dedoc/scramble ^0.13.48. Any Laravel service on an older Scramble minor must upgrade Scramble first. The removal of the package’s own InfoObject and the change to OneOf::setDiscriminator() accepting Scramble’s Discriminator are source-level breaking changes, so integration is not a drop-in Composer bump if teams used those APIs.
• Technical risk: Medium to high for existing consumers. The package is still on 0.x, and 0.30.0 demonstrates breaking changes in a minor release. The primary risks are:
  • Scramble version lockstep: teams must track Scramble releases closely.
  • Custom OpenAPI schema code using InfoObject or discriminator mappings may fail at runtime or produce altered specs.
  • Generated OpenAPI diffs can break downstream contract tests, SDK generation, or API gateway imports even when PHP tests pass.
  • The new flatten_deep_query_parameters behavior may change filter parameter schemas, which is useful but also a spec-level behavioral change.
• Key questions:
  • Which Laravel services use spectacular, and what Scramble versions are currently locked?
  • Does any application code instantiate the removed InfoObject or call OneOf::setDiscriminator() directly?
  • Are OpenAPI specs consumed by external partners, SDK generators, or API gateways where schema diffs require approval?
  • Do current APIs use deep query parameters for filters, and would the new flattening behavior improve or disrupt generated client ergonomics?
  • Is there an internal owner for API documentation tooling and a CI check that diffs generated OpenAPI specs?

Integration Approach

• Stack fit: Best suited to Laravel applications already using Scramble for API documentation. Teams should confirm PHP and Laravel version compatibility with dedoc/scramble ^0.13.48 before upgrading spectacular. Services without Scramble should evaluate Scramble first; adding spectacular only for discriminator or info-object helpers may not justify the dependency churn.
• Migration path:
  1. Inventory all services using bambamboole/spectacular and their current dedoc/scramble constraints.
  2. Upgrade dedoc/scramble to ^0.13.48 in a branch and resolve framework/PHP compatibility issues.
  3. Upgrade spectacular to 0.30.0.
  4. Search code and tests for InfoObject and OneOf::setDiscriminator() usage; refactor to Scramble’s Discriminator and remove reliance on the deleted InfoObject.
  5. Regenerate OpenAPI specs and diff them against the previous output.
  6. Validate downstream consumers: contract tests, SDK generation, Postman collections, gateway imports, and partner-facing documentation.
• Compatibility: The release explicitly requires Scramble ^0.13.48, so Composer will block incompatible combinations. The API break is limited to discriminator construction and the removed InfoObject; teams not using those APIs may only need the Scramble bump. The new flatten_deep_query_parameters support should be treated as opt-in behavior driven by Scramble configuration and verified against existing filter schemas.
• Sequencing: Treat this as a coordinated dependency upgrade rather than an isolated package bump. Recommended sequence: dependency audit → Scramble upgrade → spectacular upgrade → code refactor for removed/changed APIs → spec regeneration and diff review → CI contract validation → staged rollout. If multiple services share generated specs or client SDKs, upgrade documentation generation in one service first as a canary before broad rollout.

Operational Impact

• Maintenance: Expect ongoing maintenance to track Scramble releases. Pin dedoc/scramble and bambamboole/spectacular to compatible ranges, and add Dependabot/Renovate visibility for both. Because spectacular is 0.x, minor upgrades should be treated as potentially breaking and validated through generated-spec diffs.
• Support: The package is community-maintained. Internal teams should identify an owner for API documentation tooling and define an escalation path for Scramble compatibility issues. Relying on upstream Scramble releases means support incidents may require pinning or patching until a compatible spectacular release lands.
• Scaling: OpenAPI generation typically runs at build or CI time, so runtime scaling impact is low. Large Laravel APIs may see increased CI duration and larger spec artifacts. Teams generating SDKs or gateway configs from specs should cache generated artifacts and avoid regenerating on every application request.
• Failure modes:
  • Composer dependency conflict between spectacular and the installed Scramble version.
  • Fatal errors from removed InfoObject references or changed discriminator method signatures.
  • Silent OpenAPI schema changes, especially around discriminator mappings or flattened deep query parameters.
  • CI failures in downstream contract tests or SDK generation after spec changes.
  • Inconsistent specs across services if only some are upgraded.
• Ramp-up: Teams familiar with Scramble and OpenAPI will need limited ramp-up. Teams new to the stack should budget time for OpenAPI concepts, discriminator/polymorphism modeling, and CI spec-diff tooling. A short internal runbook covering upgrade steps, spec diff review, and rollback via version pinning will reduce operational friction.