- How do I install and set up L5-Swagger in a Laravel app?
- Install it with composer require darkaonline/l5-swagger, then publish the config and assets using the vendor:publish command for L5Swagger\L5SwaggerServiceProvider. Set the paths and scanOptions entries in config/l5-swagger.php so the generator knows where your base spec and annotated source files live. Run php artisan l5-swagger:generate and open the /api/documentation route to view Swagger UI. The step-by-step details live in the package wiki under Installation & Configuration.
- Which Laravel and PHP versions does darkaonline/l5-swagger support?
- Version 9.x targets Laravel 11 and 12, while 11.x tracks Laravel 13, and 8.x covers older Laravel 9 and 10 projects. From v9 onward the package requires PHP 8.2 or newer. Pin the package major in composer.json and let Composer resolve minors, then re-check compatibility whenever you bump your Laravel major.
- Does L5-Swagger still support Doctrine annotations, or only PHP 8 attributes?
- Version 10 removed the abandoned Doctrine annotation reader, so current releases expect PHP 8 attributes such as #[OA\Info] and #[OA\Get]. If your codebase still contains legacy annotation docblocks, they must be converted before you can move to v10 or later. Plan the attribute migration per bounded context rather than across the entire application at once.
- How do I generate the OpenAPI spec in CI with the l5-swagger:generate command?
- Run php artisan l5-swagger:generate as a build step after Composer install and commit or archive the resulting JSON/YAML as the artifact of record. This avoids regenerating at request time and gives you a diffable spec for code review and contract tests. Keep the generation step gated on your CI environment config so developers can still generate locally on demand.
- How do I protect or disable the /api/documentation Swagger UI route in production?
- The docs UI and spec are served over HTTP routes, so treat them as an externally reachable surface. Gate them by environment, middleware, basic auth, or an IP allowlist, or disable the route entirely in production and publish only the generated JSON spec. Keep the package patched: a path-traversal issue was fixed in 8.6.4 and a Swagger UI CVE drove a version floor in 8.5.1.
- Can L5-Swagger serve multiple API specs in one Laravel application?
- Yes. The config file supports multiple documentation entries, each with its own paths, scanOptions, route, and UI view, which suits public, internal/admin, and partner APIs in a modular monolith. You can also customise the generator factory and processor ordering per definition. This avoids forking the package just to document more than one API surface.
- How do I configure Passport, Sanctum or OAuth2 authentication in Swagger UI?
- Define the security schemes in your base spec or attributes and reference them from the protected operations, then enable the matching UI options in config/l5-swagger.php. Passport and OAuth2 flows are covered in the package wiki, and Sanctum bearer tokens work as an HTTP bearer scheme. Swagger UI options such as persist authorization, PKCE, deep linking, and doc expansion are all config-driven.
- Is darkaonline/l5-swagger actively maintained and safe to depend on in production?
- It has very high Packagist adoption and steady releases, but maintenance is concentrated in a small contributor group led by the maintainer and supported through GitHub Sponsors. Expect an upgrade roughly once a year as it tracks swagger-php and Laravel majors, so budget time alongside your framework upgrades. Because it is a thin adapter around swagger-php and Swagger UI, most risk sits in keeping those dependencies current rather than in the Laravel glue code.
- What are the alternatives to L5-Swagger for Laravel API documentation?
- You can hand-maintain an OpenAPI YAML file and serve it with any static docs tool, or use an attribute-driven generator such as Scramble that infers schemas from your code. L5-Swagger itself is only a wrapper around zircote/swagger-php and swagger-api/swagger-ui, so it is the natural choice if you want the standard Swagger UI experience inside Laravel. Where the spec is a contract for client codegen, a hand-reviewed spec file may still be the safer source of truth.
- How do I upgrade L5-Swagger between major versions like 8.x, 9.x, 10.x and 11.x?
- Follow the migration guides on the GitHub wiki and align the package major with your Laravel major: 8.x for Laravel 9 and 10, 9.x for Laravel 11 and 12, 11.x for Laravel 13. The two biggest breaking changes so far are the PHP 8.2 and Laravel 11 floors in v9 and the removal of Doctrine annotations in v10. Pin the major, run l5-swagger:generate in CI after each bump, and diff the generated spec to catch regressions.