Open-source project
DarkaOnLine/L5-Swagger avatar
DarkaOnLine/L5-Swagger

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

OpenApi or Swagger integration to Laravel

2,935 stars410 forksPHPMIT

At a glance

What is it?
L5-Swagger packages swagger-php and swagger-ui for Laravel. It generates a spec from PHP attributes and serves the UI, but it does not define your API contract for you.
Who is it for?
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.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 6 days ago.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • DarkaOnLine/L5-Swagger2,935 ★ · -2
Star history
Repository2026-09-242026-11-15
DarkaOnLine/L5-Swagger2.9k2.9k

-2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

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, 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 repository layout shows config/, src/ and resources/ directories at the top level. The README says L5-Swagger packages up swagger-php and swagger-ui in a Laravel-friendly fashion and tries to make it easy to serve, and for how to write the specification it points to the swagger-php documentation. The practical consequence is that your spec is only as complete as the swagger-php annotations you write, because the README states that the actual Swagger spec is beyond the scope of this package.

Installing L5-Swagger and generating a first spec

Installation goes through Composer: the package is darkaonline/l5-swagger on Packagist, 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.

Install with `composer require darkaonline/l5-swagger`. After adding swagger-php OpenAPI attributes, run `php artisan l5-swagger:generate`; the default documentation URL is `/api/documentation`. Check the wiki's version matrix for your Laravel and PHP versions.

What the published config controls

The repository has a config/ directory at its top level, and the README sends configuration questions to the wiki page Installation & Configuration, which is the place to check before changing any setting. The documentation routes are public by default; configure route middleware when access must be restricted. During development, `L5_SWAGGER_GENERATE_ALWAYS=true` enables regeneration on each request.

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 infer a complete spec from routes alone. That is the limitation that matters most, and it is stated plainly in the disclaimer rather than buried: the actual Swagger spec is beyond the scope of the package. 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. The installation wiki documents an option to regenerate on each request for development, 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.

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

What is Swagger and why is it used?

Swagger is the specification format that L5-Swagger serves through swagger-ui; the package wraps swagger-php and swagger-ui for Laravel and states that the actual Swagger spec is beyond its scope. It is used to produce a machine-readable description of an API that a UI can render.

What is replacing Swagger?

The README does not discuss a replacement for Swagger. It describes L5-Swagger as a wrapper of swagger-php and swagger-ui adapted to work with Laravel, and points to the swagger-php documentation for the specification itself.

Is Swagger UI FastAPI?

No. Swagger UI is the interface bundled by L5-Swagger through swagger-ui; FastAPI is a Python framework and is not mentioned anywhere in this repository. L5-Swagger is a PHP package for Laravel.

Is Swagger outdated?

The README does not make any claim about Swagger being outdated or current; it only states that the package wraps swagger-php and swagger-ui and that the specification itself is outside its scope. The package's last push was on 2026-10-29.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/darkaonline-l5-swagger.svg)](https://hysenlabs.com/projects/darkaonline-l5-swagger)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/darkaonline-l5-swagger.svg)](https://hysenlabs.com/projects/darkaonline-l5-swagger)

Was this useful?