PHPackages riconijeboer/laravel-to-swagger - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. riconijeboer/laravel-to-swagger AbandonedArchivedLibrary[API Development](/categories/api) riconijeboer/laravel-to-swagger =============================== This package aims to bring you the easiest way to create a Swagger / OpenApi 3 config for your Laravel API's. v2.5.0(4y ago)222.2kMITPHPPHP ^7.4|^8.0|^8.1 Since Mar 21Pushed 4y ago1 watchersCompare [ Source](https://github.com/RicoNijeboer/laravel-to-swagger)[ Packagist](https://packagist.org/packages/riconijeboer/laravel-to-swagger)[ Docs](https://github.com/riconijeboer/laravel-to-swagger)[ RSS](/packages/riconijeboer-laravel-to-swagger/feed)WikiDiscussions v2.x Synced 2d ago READMEChangelog (10)Dependencies (13)Versions (34)Used By (0) Laravel to Swagger ================== [](#laravel-to-swagger) [ ![Packagist version](https://camo.githubusercontent.com/a9bc09e784c8ffbc4c2bf4cecc2c1bb5f210bff0f9eff8ae00b099d0ca8ad8f1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7269636f6e696a65626f65722f6c61726176656c2d746f2d73776167676572)](https://packagist.org/packages/riconijeboer/laravel-to-swagger "Packagist version")[![Packagist downloads](https://camo.githubusercontent.com/4f3add3e2215603f52dc4e375031e427ad4061e07bc8b1759954d1eaecd1dc8d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f7269636f6e696a65626f65722f6c61726176656c2d746f2d73776167676572)](https://camo.githubusercontent.com/4f3add3e2215603f52dc4e375031e427ad4061e07bc8b1759954d1eaecd1dc8d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f7269636f6e696a65626f65722f6c61726176656c2d746f2d73776167676572) This package aims to bring the easiest path to creating a Swagger / OpenApi 3 config for your Laravel API's. Installation ------------ [](#installation) For local only installation go [here](#local-only-installation) 1. `composer require riconijeboer/laravel-to-swagger` 2. `php artisan vendor:publish --provider="RicoNijeboer\Swagger\SwaggerServiceProvider"` - This will publish the package's config-file and migrations ### Local Only installation [](#local-only-installation) 1. `composer require riconijeboer/laravel-to-swagger --dev` 2. `php artisan vendor:publish --provider="RicoNijeboer\Swagger\SwaggerServiceProvider"` - This will publish the package's config-file and migrations 3. Finally, you should prevent the Swagger package from being [auto-discovered](https://laravel.com/docs/8.x/packages#package-discovery) by adding the following to your `composer.json` file: ``` "extra": { "laravel": { "dont-discover": [ "riconijeboer/laravel-to-swagger" ] } } ``` 4. Now that auto-discovery is disabled you should manually register the service provider in the `register` method of your `App\Providers\AppServiceProvider` class. In the example we only enable the package when we are running in a `local` environment. ``` /** * Register any application services. * * @return void */ public function register() { if ($this->app->environment('local')) { $this->app->register(\RicoNijeboer\Swagger\SwaggerServiceProvider::class); } } ``` ### Requirements [](#requirements) - **PHP**: 7.4.x or 8.0.x - **Laravel**: v6 / v7 / v8 ### Updating [](#updating) When changes are made that impact existing users, I will make sure that they are documented in the [Changelog](#changelog). These will contain changes like database columns added / removed / renamed. Or functional changes that need action within your code. #### v2.1.x to v2.2.x [](#v21x-to-v22x) - When updating from v2.1 to v2.2 add a nullable `route_domain` string-column to the `swagger_batches` domain. `$table->string('route_domain')->nullable();` Usage ----- [](#usage) ### Registering the Redoc Documentation route. [](#registering-the-redoc-documentation-route) Reading a Swagger config is an acquired taste. To display the config in a more user-friendly way I've used [Redoc](https://github.com/Redocly/redoc). To register the documentation route you can simply add the code below to your `routes/web.php` file or within a ServiceProvider. ``` use RicoNijeboer\Swagger\Swagger; Swagger::routes(); ``` #### Customizing the /docs Url [](#customizing-the-docs-url) ``` use RicoNijeboer\Swagger\Http\Routing\RouteRegistrar; use RicoNijeboer\Swagger\Swagger; Swagger::routes(fn (RouteRegistrar $routes) => $routes->forDocumentation('/different-url/docs')); ``` #### Customizing the routing group [](#customizing-the-routing-group) ``` use RicoNijeboer\Swagger\Swagger; Swagger::routes(null, [ 'prefix' => 'swagger', // This will do Route::group(['prefix' => 'swagger']) under the hood. ]); ``` #### Using Swagger UI instead of Redoc [](#using-swagger-ui-instead-of-redoc) You can disable Redoc and use Swagger UI instead by passing `false` as the second parameter to the `forDocumentation` method. ``` use RicoNijeboer\Swagger\Http\Routing\RouteRegistrar; use RicoNijeboer\Swagger\Swagger; Swagger::routes(fn (RouteRegistrar $routes) => $routes->forDocumentation('/docs', false)); ``` ### Registering routes for your Swagger config [](#registering-routes-for-your-swagger-config) To add routes to your Swagger config you want to add the `\RicoNijeboer\Swagger\Http\Middleware\SwaggerReader` middleware. Which is aliased to both `swagger_reader` and `openapi_reader`. ``` Route::middleware('swagger_reader')->get('products', [ProductController::class,'index']); ``` #### Tagging / Grouping routes [](#tagging--grouping-routes) To group multiple routes in Swagger you add a tag to the path. Using the package you may register a tag through adding a middleware to your route and supplying it with the desired tags as shown below. > Keep in mind that the `swagger_tag` (`\RicoNijeboer\Swagger\Http\Middleware\SwaggerTag`) middleware is only going to tag your request once the batch has been stored. If a batch has not been created it will continue and do nothing, no questions asked. ``` // Using the SwaggerReader middleware Route::middleware('swagger_reader:tag-one,tag-two')->get('products', [ProductController::class,'index']); // Using the SwaggerTag middleware Route::middleware('swagger_tag:tag-one,tag-two')->get('products', [ProductController::class,'index']); ``` Configuration ------------- [](#configuration) ### Database connection [](#database-connection) You may want your database entries from the Laravel to Swagger package in a separate database or to have an extra prefix. To do this, add an extra connection to your Laravel project and just simply set the `swagger.database.connection` config value. For example, if I want all parts of the Swagger database to be in a connection I've named `swagger`, I'd set the config like below. ``` return [ //... 'database' => [ 'connection' => 'swagger', ], //... ]; ``` ### Evaluation delay, configure how often your endpoints are re-evaluated [](#evaluation-delay-configure-how-often-your-endpoints-are-re-evaluated) By default, the package only updates the configuration of your route every 12 hours, within a couple restraints. This does keep into account the response codes you are sending back to your users. If you want to change this to for example 24 hours, you'd set the `swagger.evaluation-delay` config value to the time in seconds. ``` return [ //... 'evaluation-delay' => 24 * 60 * 60, // Or 86400 //... ]; ``` ### Swagger Meta Information [](#swagger-meta-information) Swagger allows you to provide the users with a bit of info about your API; a title, a description and a version. In the config there is a `swagger.info` array where you can add your API's title, description and version, as shown below. ``` return [ //... 'info' => [ 'title' => 'Laravel to Swagger', 'description' => null, 'version' => '2.1.2', ], //... ]; ``` ### Swagger Servers [](#swagger-servers) Swagger allows you to show the user servers that you can access the API from. A basic setup would be the one below; - You have one API where your users can access live data and one where they can access some demo information. ``` return [ //... 'servers' => [ [ 'url' => 'http://api.example.com/v1', 'description' => null, ], [ 'url' => 'http://demo-api.example.com/v1', 'description' => 'The demo environment description', ], ], //... ]; ``` #### Server templating [](#server-templating) Swagger also supports [Server templating](https://swagger.io/docs/specification/api-host-and-base-path/). You are able to add variables to your server which gives you the possibility to obfuscate the urls a bit. An example from their documentation is a server where you have `https://{customerId}.saas-app.com:{port}/v2` as the URL. This is translated to their Yaml as shown below. They define the url, containing its variables, and describe what the variables do and what their default values are. Laravel to Swagger supports basically the same format as the Yaml file, below the Yaml you can see how you translate it to the Swagger config. I've added very light validation to this, so if the Swagger UI / Redoc UI breaks try to first ensure that you've correctly configured the config according to the [Swagger docs](https://swagger.io/docs/specification/api-host-and-base-path/) **Swagger Yaml** ``` servers: - url: https://{customerId}.saas-app.com:{port}/v2 variables: customerId: default: demo description: Customer ID assigned by the service provider port: enum: - '443' - '8443' default: '443' ``` **Laravel to Swagger Config** ``` return [ //... 'servers' => [ [ 'url' => 'https://{customerId}.saas-app.com:{port}/v2', 'variables' => [ 'customerId' => [ 'default' => 'demo', 'description' => 'Customer ID assigned by the service provider', ], 'port' => [ 'enum' => [ '443', '8443', ], 'default' => '443', ], ], ], ], //... ]; ``` ### Redoc Version [](#redoc-version) Let's say you run into a bug within the Redoc that the team behind Redoc has fixed in a newer version, and I have not updated the package yet to have the fixed version used. I have added a config value (`swagger.redoc.version`), so you don't have to mess around with things like published views or anything; You can simply change the version based on their [releases](https://github.com/Redocly/redoc/releases), at the time of writing this documentation the latest version is `v2.0.0-rc.53`. ``` return [ //... 'redoc' => [ 'version' => 'v2.0.0-rc.53', //... ], //... ]; ``` ### Grouping Tags [](#grouping-tags) [![redoc-only](https://camo.githubusercontent.com/5351c1d6b4c1a63d3d73a893cd3e543485cc4115fada255228a4ad770f71025a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5265646f632532304f6e6c792d7265642e737667)](https://camo.githubusercontent.com/5351c1d6b4c1a63d3d73a893cd3e543485cc4115fada255228a4ad770f71025a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5265646f632532304f6e6c792d7265642e737667) If you are using Redoc you are able to group your tags by using the config. In the example below a group called "User Management" is created containing the tags "Users", "Admin" and "API keys". > Tags that are not grouped by you will be added under a default group, > the name of which can be changed using the config (`swagger.redoc.default-group`) ``` return [ //... 'redoc' => [ //... 'default-group' => null, 'tag-groups' => [ [ 'name' => 'User Management', 'tags' => [ 'Users', 'Admin', 'API keys' ], ], ], ], //... ]; ``` ### Adding a logo [](#adding-a-logo) [![redoc-only](https://camo.githubusercontent.com/5351c1d6b4c1a63d3d73a893cd3e543485cc4115fada255228a4ad770f71025a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5265646f632532304f6e6c792d7265642e737667)](https://camo.githubusercontent.com/5351c1d6b4c1a63d3d73a893cd3e543485cc4115fada255228a4ad770f71025a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5265646f632532304f6e6c792d7265642e737667) You can add a logo to the sidebar in your Redoc visualization by adding a full-url to the `swagger.info.logo.url`. > The logo is only displayed when you use the Redoc documentation route. ``` return [ //... 'info' => [ //... 'logo' => [ 'url' => 'https://picsum.photos/300/200', ], ], //... ]; ``` Testing ------- [](#testing) ``` composer test ``` Credits ------- [](#credits) - [Rico Nijeboer](https://github.com/RicoNijeboer/) - [All Contributors](https://github.com/RicoNijeboer/laravel-to-swagger/graphs/contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. Changelog --------- [](#changelog) All notable changes can be found in the [CHANGELOG.md](CHANGELOG.md). ### Health Score 35 — LowBetter than 79% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity24 Limited adoption so far Community7 Small or concentrated contributor base Maturity72 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~10 days Recently: every ~42 days Total 34 Last Release 1548d ago Major Versions v1.x-dev → v2.0.02021-05-14 PHP version history (3 changes)v1.0.0PHP >=7.4 v2.0.0PHP ^7.4|^8.0 v2.5.0PHP ^7.4|^8.0|^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/26306300?v=4)[Rico Nijeboer](/maintainers/RicoNijeboer)[@RicoNijeboer](https://github.com/RicoNijeboer) --- Top Contributors [![RicoNijeboer](https://avatars.githubusercontent.com/u/26306300?v=4)](https://github.com/RicoNijeboer "RicoNijeboer (10 commits)") --- Tags apidocumentationlaravellaravel-documentationlaravel-to-openapilaravel-to-openapi3laravel-to-swaggerlaravelframeworklow-levelnijeboeropenapi3ricoriconijeboerswaggerapilaraveldocumentationswaggeropenapilaravel documentationriconijeboerlaravel-to-swaggerlaravel-to-openapi ### Code Quality TestsPHPUnit Static AnalysisPsalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/riconijeboer-laravel-to-swagger/health.svg) ``` [![Health](https://phpackages.com/badges/riconijeboer-laravel-to-swagger/health.svg)](https://phpackages.com/packages/riconijeboer-laravel-to-swagger) ``` ### Alternatives [darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 2.9k34.0M112](/packages/darkaonline-l5-swagger)[dedoc/scramble Automatic generation of API documentation for Laravel applications. 2.0k7.8M57](/packages/dedoc-scramble)[darkaonline/swagger-lume OpenApi or Swagger integration to Lumen 3372.3M3](/packages/darkaonline-swagger-lume)[scalar/laravel Render your OpenAPI-based API reference 6183.9k2](/packages/scalar-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)