Swagger Bundle Laravel Package

Product Decisions This Supports

• API-first vs. retro-documentation. Decides whether we generate the OpenAPI/Swagger spec from existing Symfony controllers (annotations in place) or invest in a spec-first workflow where the YAML is authored and code is generated from it. This package only supports the former.
• Build vs. buy vs. adopt. A concrete answer to "do we write our own spec-generation glue, adopt a Symfony bundle, or standardize on a maintained library like zircote/swagger-php or nelmio/api-doc-bundle?"
• Developer portal and partner onboarding. A machine-readable spec is a prerequisite for hosted docs (Readme, Stoplight, Bump.sh), partner sandboxes, and API catalogs — this package is one way to produce that artifact from a Symfony codebase.
• Gateway and platform config. OpenAPI output drives AWS API Gateway imports, Kong/Apigee route definitions, and SDK/client generation; tooling choice here affects how much of that pipeline is automated.
• Contract testing and versioning. Spec generation in CI enables schema-diff checks (breaking-change detection) and lets us make deprecation/versioning decisions visible to consumers rather than buried in code.
• Infrastructure roadmap signals. Whether we are on a Symfony version where this package's approach (annotations) is even viable determines a forced migration to PHP 8 attributes — a roadmap item in its own right.

When to Consider This Package

Consider only if:

• You maintain a legacy Symfony 2.x/3.x/4.x application that already carries swagger-php annotations in controllers and entities.
• You want a thin bundle to wire swagger-php into Symfony's DI/container and expose a documentation route, without writing that plumbing yourself.
• The audience is internal, the API surface is stable, and documentation fidelity is "nice to have" rather than contractual.

Look elsewhere — and this is the default recommendation — if:

• Adoption risk is disqualifying. The repository shows zero stars, zero dependents, and no visible release/maintenance signal. A documentation bundle with no consumer base has no one to report breakage, no security patch path, and no support channel. For anything customer-facing or long-lived, that is a hard no.
• You are on Symfony 5/6/7 or PHP 8. The annotation-based approach this wraps is superseded by attributes; use nelmio/api-doc-bundle (the de facto Symfony standard) or swagger-php directly.
• You need OpenAPI 3.x/3.1 features (callbacks, links, richer schema composition). Pin the underlying swagger-php version before assuming support.
• The "savings" are an hour of DI configuration. The value of this bundle is the wrapper, not the engine; paying an unmaintained-dependency tax for a thin wrapper is a poor trade.
• You need a vendor relationship, SLA, or security review sign-off. None of those exist here.

How to Pitch It (Stakeholders)

To executives (one paragraph): We evaluated timeinc/swagger-bundle, a Symfony integration for annotation-based Swagger/OpenAPI generation. It is effectively a thin convenience wrapper with no measurable adoption (no stars, no dependents, no active maintenance signal). Adopting it would save roughly a day of setup while creating an unpatched, unsupported dependency in our API documentation path — the exact layer partners and gateways read from. Recommendation: do not adopt; standardize on a maintained alternative (nelmio/api-doc-bundle for Symfony, or swagger-php used directly). The strategic decision — annotation-driven vs. spec-first API documentation — is worth making now regardless of tool, because it gates partner onboarding, SDK generation, and gateway automation.

To engineering (one paragraph): This is swagger-php plus Symfony container/route wiring. If we're on a legacy Symfony app with annotations already written, it's a short-term bridge at best; on Symfony 5+ with PHP 8 attributes, it's the wrong abstraction. We get the same output by using swagger-php directly or nelmio/api-doc-bundle, both of which are actively maintained and have real user bases. Propose a short spike on Nelmio (one controller, one spec export, one CI schema-diff check) and treat this package as historical reference only.