Swagger Bundle Laravel Package

Product Decisions This Supports

• Developer-facing API documentation as a product surface. SwaggerBundle lets the team derive OpenAPI/Swagger specs from existing Laravel controllers and annotations, so the decision to ship a public or partner-facing API portal becomes an engineering-configuration task rather than a multi-sprint docs project.
• Build vs. buy for API contracts. Rather than building and maintaining an in-house spec generator or hand-writing YAML that drifts from code, adopting this package trades a small integration cost for an externally maintained generator. Useful when the roadmap includes SDK generation, Postman collections, or gateway imports that all consume OpenAPI.
• Contract-first vs. code-first sequencing. Because specs are generated from the codebase, this package supports a code-first workflow: ship endpoints, publish the contract, then layer on partner onboarding, mock servers, and contract tests. If the roadmap instead demands contract-first (spec authored, then code generated), this package is the wrong lever.
• Scope decisions for partner/API programs. A reliable generated spec is a prerequisite for API versioning policy, deprecation communication, and third-party integration SLAs — decisions that otherwise get blocked on "we don't have current docs."
• Release-train and platform-upgrade planning. The v2.0.0 bump to Symfony 8.0 is a platform-support signal, not a feature. It feeds directly into the decision of when the platform team can move the Laravel baseline forward, and which product teams must be resourced for that migration.

When to Consider This Package

Consider it when:

• The product exposes (or plans to expose) HTTP APIs to external consumers — partners, customers, or an internal platform team — and documentation accuracy is a recurring support cost.
• The team is standardized on Laravel and is willing to annotate controllers as part of the definition of done.
• There is a downstream consumer of OpenAPI: SDK generation, API gateway import, contract testing, or a developer portal.
• The current Laravel/Symfony baseline is compatible with the package's supported matrix. v2.0.0 moves to Symfony 8.0, a major-version alignment — treat this as breaking. Confirm Laravel version constraints, PHP version floors, and transitive dependency conflicts before planning adoption or upgrade, and pin the version in composer.json accordingly.

Look elsewhere when:

• The baseline is on an older Laravel/Symfony line and cannot absorb the v2.0.0 platform requirement; staying on v1.1.1 means accepting a maintenance dead-end, so evaluate alternatives at that point.
• The API is contract-first or spec-authored by hand; a runtime-introspection generator adds ceremony without benefit.
• Documentation volume is small and stable enough that a static spec plus CI diffing is cheaper than a bundle.
• Alternatives better fit the constraints — for example annotation-free runtime introspection, or a Postman/OpenAPI-first toolchain — particularly if the team wants zero annotation overhead in controllers.
• Maintenance responsiveness is a hard requirement. v2.0.0 is a single dependency-bump PR; that is a reasonable signal of upkeep but not evidence of an active feature roadmap. Score it against alternatives on release cadence and issue responsiveness.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, low-risk enabler for API-driven revenue — partner integrations, paid API tiers, and internal platform reuse all depend on accurate, current API documentation. Adopting the bundle converts documentation from a recurring manual cost into an automated output of work we already do. The v2.0.0 release is a platform alignment to Symfony 8.0, not a feature release; the material implication is a compatibility gate on our Laravel baseline, which the platform team should sequence deliberately. Cost is bounded to integration and annotation discipline; the primary risk is dependency alignment, not vendor lock-in.

For engineering: v2.0.0 is a breaking major — it moves the package onto Symfony 8.0, which cascades into supported Laravel and PHP versions. Before upgrading, verify our framework baseline, resolve transitive constraints, pin the version, and validate that generated specs are byte-stable in CI. Expect annotation overhead in controllers; treat spec freshness as a build-time gate rather than a periodic chore. If we cannot move the baseline now, stay on v1.1.1 with a documented expiry and an owner for the eventual migration — do not let a pinned version silently become an unowned dependency.