Weave Code
Swagger Bundle Laravel Package
timeinc/swagger-bundle
A Symfony bundle that generates Swagger/OpenAPI documentation for your REST API from PHP annotations, keeping interactive specifications in sync with your code and making it easy to expose and maintain API docs alongside your application.
Implementation of swagger-php for Symfony
Frequently asked questions about Swagger Bundle
- Can I use timeinc/swagger-bundle in a Laravel application?
- No, not as a package. timeinc/swagger-bundle is a Symfony bundle, and its entire value is Symfony glue: a Bundle subclass, a DependencyInjection extension for the config tree, compiler passes, and service wiring. Laravel has no bundle registration mechanism and no config-tree extension contract, so there is nothing in this package you can boot. The underlying engine, zircote/swagger-php, is framework-agnostic, so install that directly instead.
- What does timeinc/swagger-bundle actually do?
- It wraps zircote/swagger-php for Symfony applications. It registers the swagger-php services in the container, exposes a configuration tree for scan paths and output targets, and wires generation into the Symfony lifecycle. The actual annotation and attribute scanning plus spec generation is all done by swagger-php itself. The bundle's net contribution is a few hundred lines of container wiring.
- Why does Composer fail when installing timeinc/swagger-bundle in Laravel?
- Its Symfony component constraints target older Symfony releases, which collide with the Symfony 6 and 7 components that Laravel 10 and 11 pull in. It also pins a pre-4.x swagger-php, which conflicts with current versions. Dependency resolution will typically fail before you write a single line of code. Forcing installation with ignore-platform-reqs or similar flags does not make the bundle bootable in Laravel.
- Is timeinc/swagger-bundle still maintained?
- No. The package has zero stars and zero dependents, and the TimeInc open source organisation has been effectively dormant since the Meredith acquisition. There is no release cadence, no issue triage, and no security response process. Adopting it means forking and maintaining it internally.
- What is the best Laravel alternative to timeinc/swagger-bundle?
- Start with zircote/swagger-php ^4 or ^5 invoked directly from an Artisan command, since that is the same engine the bundle wraps with no framework lock-in. If you want a Laravel-native wrapper with a bundled Swagger UI route and published config, use darkaonline/l5-swagger. If attribute authoring is unattractive and code-first inference is acceptable, dedoc/scramble removes annotation drift risk. If the primary audience is humans reading docs rather than machines consuming a spec, knuckleswtf/scribe is the better fit.
- Does timeinc/swagger-bundle support OpenAPI 3.1 and PHP 8 attributes?
- No. The bundle predates swagger-php 4.x, which means it targets annotation-based scanning with @OA docblocks and an older PHP runtime. OpenAPI 3.1 output requires swagger-php 4 or 5 with PHP 8 attributes, an API this bundle has no knowledge of. Reaching modern spec output requires dropping the bundle and using the library directly.
- Which PHP and Laravel versions does timeinc/swagger-bundle support?
- None, as far as Laravel is concerned, because there is no integration path that produces working software in a Laravel app. The bundle itself targets older Symfony and PHP versions that are past end of life. For a current Laravel target, aim for PHP 8.1 or newer, swagger-php ^4 or ^5, and Laravel 10 or 11, all of which the underlying library supports and the bundle cannot reach.
- How do I migrate from timeinc/swagger-bundle to a Laravel-friendly setup?
- With zero dependents there is almost certainly no existing consumer, so treat the work as greenfield rather than a migration. Lift the scan paths and output configuration out of the bundle's YAML or PHP config into a plain config file or an Artisan command signature, then re-pin swagger-php to a current major. Convert @OA annotations to #[OA] PHP attributes, which is the breaking change introduced in swagger-php 4 and by far the largest line item of effort. Finally, drop all Symfony service definitions, since Laravel will never load them.
- Can I use zircote/swagger-php directly in Laravel without a wrapper?
- Yes. swagger-php is framework-agnostic, so you can scan your application paths from an Artisan command and write the resulting JSON or YAML into storage. From there you either commit the artifact, serve it from a route, or feed it to any static docs UI. This avoids bundle and wrapper maintenance entirely and keeps you on the current upstream release.
- Should the OpenAPI spec be generated at build time or served by a live docs route in production?
- These have very different risk profiles. Build-time generation as a CI artifact keeps documentation out of the request path and lets you gate releases on spec correctness through contract testing or SDK generation. A runtime docs route is fine for internal, human-facing documentation but adds another surface to authenticate and secure. Decide based on whether machines consume the spec or only people read it.
Weaver
How can I help you explore Laravel packages today?