- How do I install darkaonline/swagger-lume in a Lumen app?
- Run composer require darkaonline/swagger-lume, then manually register the package service provider in bootstrap/app.php because Lumen does not support package auto-discovery. After registering, publish the configuration with the package's vendor:publish command and start annotating your controllers. The whole setup is a few lines and does not require changes to your application code beyond the annotations.
- Which Lumen versions does swagger-lume support?
- The package major version tracks the framework major, so release 11.0 targets Lumen 11 and 10.x targets Lumen 10. If you are still on Lumen 10 you should stay on the 10.x line of the package rather than forcing 11.0. Plan a coordinated Lumen and package major upgrade, and add that pairing to your upgrade runbook so it is not discovered mid-sprint.
- Does swagger-lume work with Laravel, or is it Lumen only?
- SwaggerLume is built specifically for Lumen's minimal stack, including its reduced Artisan command set and lack of package auto-discovery. For full Laravel applications, the same maintainer publishes darkaonline/l5-swagger, which is the equivalent integration for Laravel. Trying to use SwaggerLume in Laravel is unnecessary since the Laravel package covers the same workflow.
- How do I generate the OpenAPI specification file?
- The package registers a console command that invokes swagger-php to scan your configured paths for annotations or attributes and writes the compiled OpenAPI document to your configured output location. Point the scan paths at your controllers and models, then run the generation command as part of your build or deployment step. The generated artifact is what Swagger UI and any downstream consumers such as SDK generators or API gateways read.
- Which swagger-php version does swagger-lume use, and does it support OpenAPI 3.1?
- The wrapper is pinned to swagger-php v4, so OpenAPI 3.1 output is not available until the package moves to swagger-php v5. Because of that pin, the v4 to v5 transition and its removal of Doctrine annotation support are out of reach for now. Pin and lock the dependency explicitly in your composer.json rather than inheriting the constraint transitively.
- Can I use PHP 8 attributes instead of Doctrine annotations?
- Yes. With swagger-php v4 you can document your API using PHP 8 attributes, and legacy Doctrine annotation syntax also remains viable on this version. Attributes are the forward-looking choice because swagger-php v5 drops Doctrine annotation support entirely. Whichever you pick, remember to import the OpenApi\Annotations namespace in files that use the classes.
- How do I publish and customize the config, views, and assets?
- Use the package's vendor:publish command to copy the configuration file, the Swagger UI blade view, and the front-end assets into your Lumen application. Once published, you can edit the config to control scan paths, output location, route path, and UI options, and edit the view to match your branding. Publishing also makes it easier to review changes in version control instead of relying on package defaults.
- Do I need a writable storage path for the generated docs in Docker?
- Yes. The package writes the generated OpenAPI document to a storage path, so that directory must exist and be writable by your PHP process. In container images, create the directory during the build and set correct ownership, or mount a volume for it. Otherwise generation and UI serving will fail with permission or missing-file errors in production.
- Does swagger-lume validate requests or support contract testing at runtime?
- No. SwaggerLume is a build-time code generation tool with a runtime UI attached: it compiles annotations into an OpenAPI artifact and serves Swagger UI. It does not perform request or response validation, contract testing, or mock server duties. If you need those capabilities, pair the generated spec with dedicated tooling such as a gateway, a mock server, or a contract testing library.
- Is darkaonline/swagger-lume actively maintained, and what are the alternatives?
- It is a single-maintainer package with a modest star count and no commercial backing or vendor SLA, though release 11.0 added explicit Lumen 11 support and included external contributor pull requests, which is evidence of a live maintenance path. Treat the bus factor as a real consideration and pin your version. Alternatives include writing the OpenAPI document by hand or using the same author's l5-swagger if you move to full Laravel.