L5-Swagger: serving OpenAPI specs and Swagger UI from a Laravel app

The gap L5-Swagger fills in a Laravel codebase

Laravel gives you routes, controllers and form requests but nothing that emits a machine-readable API description. L5-Swagger is the adapter that turns that gap into two artefacts: a generated OpenAPI document and a served Swagger UI page. The README is explicit about scope: it calls the package a wrapper of swagger-php and swagger-ui adapted to work with Laravel, and states that the actual Swagger spec is beyond the scope of this package. That sentence is the most useful thing in the repository, because it tells you what you are buying. You are buying Laravel wiring (a config file, an artisan command, a route that serves the UI, a place to publish assets), not a spec authoring tool and not a runtime validator. The audience is a Laravel team that already writes PHP attributes for swagger-php, or is willing to, and wants the output reachable at a URL inside the same application instead of generated in a separate CI job and shipped somewhere else.

How the generation command, config and UI route connect

The pieces are visible in the repository layout. There is a config/ directory that gets published into the application, a src/ directory holding the service provider and the console command, and a resources/ directory holding the Swagger UI assets that the package serves. The flow is one-directional: swagger-php scans your PHP source for OpenAPI attributes, writes a JSON or YAML document, and the UI route reads that document at request time. Nothing in that chain inspects your routes or your controllers. If a controller action has no attribute describing it, it does not appear in the spec, and the package will not warn you. The command name appears in the search data as php artisan l5-swagger:generate, and the related searches also list L5-swagger:generate on its own, which matches a command that regenerates the document on demand rather than on every request. The practical consequence is that the spec is a build artefact. It goes stale the moment someone adds an endpoint and forgets to re-run generation, and the UI will happily serve the stale version. Teams that treat generation as a deploy step avoid that; teams that expect the UI to reflect the current code automatically will be surprised.

Installing L5-Swagger and generating a first spec

Installation goes through Composer. The package name appears in the search data as composer require darkaonline/l5-swagger, and the README points to the wiki page Installation & Configuration for the full steps. The README itself does not reproduce the install commands, so treat the wiki as the authoritative source and check it against your Laravel version before you start. After the service provider is published, the generation command writes the document that the UI route serves.

What the published config controls

Publishing the service provider drops a config file into the application's config directory, which is where the paths and the UI settings live. The related searches include L5-swagger config, so this file is where most day-to-day questions land. The structure below shows the shape of the file the package publishes, with the documentation entry, the UI route and the annotation scan paths. The values are illustrative, so read the published file before changing anything.

Running the package in its own Docker setup

The repository ships a docker-compose.yml and a Dockerfile aimed at developing the package itself, not at documenting your application. The compose file builds a service named l5-swagger-app from a Dockerfile target called local, mounts the repository at /app, and maps host port 7777 to container port 80. The Dockerfile starts from php:8.4-apache, installs Composer, and then runs composer create-project laravel/laravel l5-swagger-app before requiring the package from a local path repository. That is a useful detail: the image exists to spin up a throwaway Laravel app with the package linked in, so you can reproduce issues against a clean install. If you want to run L5-Swagger inside your own project, this compose file is not the path; you install the package into your existing app instead.

Where L5-Swagger stops being the right tool

The package does not generate a spec from your code. That is the limitation that matters most, and it is stated plainly in the disclaimer rather than buried. If your team's reason for wanting OpenAPI is to avoid hand-writing documentation, L5-Swagger does not deliver that, because the attributes are the documentation. A second limitation is that the served document is only as fresh as the last generation run. There is no documented mechanism in the README for keeping the spec in sync with the code automatically, and the README does not document rollback or versioning of generated specs either. Third, the spec is descriptive only. L5-Swagger does not validate incoming requests against the schema, so an endpoint that violates its own documented contract will still execute. If you need request validation driven by the OpenAPI document, this package is not that layer, and you should not add it expecting one. Finally, the annotation syntax is swagger-php's, not L5-Swagger's. When attributes fail to parse, the error comes from swagger-php, and the fix belongs in the swagger-php documentation, not here.

Alternatives and the difference in approach

The most direct alternative is using swagger-php and swagger-ui without the Laravel wrapper. You would generate the document in a script or a CI step and serve the UI as static files from wherever you already host static assets. The difference is ownership: with L5-Swagger, the UI route and the config live inside the Laravel application, so a developer can open the docs on any environment where the app runs, including a local one, with no separate hosting. Without the wrapper, you trade that convenience for one less dependency in composer.json and no service provider in the boot path. A second alternative is writing the OpenAPI document by hand or in a design-first editor and committing it, then serving it read-only. That inverts the workflow: the document is the source of truth and the code follows it. L5-Swagger assumes the opposite, that the PHP source is the source of truth and the document is derived. Pick based on which direction your team actually reviews changes in. There is no middle ground in this package; it does not import an existing OpenAPI file and reconcile it with your routes.

Editorial conclusion

Adopt L5-Swagger if your Laravel app already has API routes you want documented and you accept writing swagger-php attributes by hand. Do not adopt it expecting the package to infer endpoints from your controllers, and do not expect it to validate requests or responses at runtime. Before installing, check the wiki page for Installation & Configuration against your Laravel version, and confirm which swagger-php version your composer resolution pulls in, because the annotation syntax follows swagger-php, not L5-Swagger.

Frequently asked questions

Official sources

1. DarkaOnLine/L5-Swagger on GitHub
2. License: MIT
3. Project website
4. README
5. Releases