PHPackages                             vanaboom/laravel-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. vanaboom/laravel-swagger

ActiveLibrary[API Development](/categories/api)

vanaboom/laravel-swagger
========================

Swagger docs generator for Laravel api

v1.0.0(1y ago)083MITPHPPHP >=7.3 || 8.\*

Since Jan 7Pushed 1y ago2 watchersCompare

[ Source](https://github.com/vanaboom/laravel-swagger)[ Packagist](https://packagist.org/packages/vanaboom/laravel-swagger)[ RSS](/packages/vanaboom-laravel-swagger/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Laravel Swagger Docs
====================

[](#laravel-swagger-docs)

Simple to use OAS3 compatible documentation generator.
Also includes Swagger UI.

About
-----

[](#about)

This package is heavily inspired by the [darki73/laravel-swagger](https://github.com/darki73/laravel-swagger)and [kevupton/laravel-swagger](https://github.com/kevupton/laravel-swagger).
Usage is pretty similar to the [mtrajano/laravel-swagger](https://github.com/mtrajano/laravel-swagger) with the difference being:

1. OAS3 support
2. Custom decorators
3. Custom responses
4. Automatic generation (assuming relevant configuration option is turned on)
5. Inclusion of Swagger UI
6. Models generations
7. Generate operation tags based on route prefix or controller's name

Installation
------------

[](#installation)

#### Install package through composer

[](#install-package-through-composer)

```
composer require vanaboom/laravel-swagger
```

#### Publish configuration files and views

[](#publish-configuration-files-and-views)

```
php artisan vendor:publish --provider "VanaBoom\LaravelSwagger\SwaggerServiceProvider"
```

#### Edit the `swagger.php` configuration file for your liking

[](#edit-the-swaggerphp-configuration-file-for-your-liking)

Usage
-----

[](#usage)

Laravel Swagger Docs works based on recommended practices by Laravel. It will parse your routes and generate a path object for each one. If you inject Form Request classes in your controller's actions as request validation, it will also generate the parameters for each request that has them. For the parameters, it will take into account wether the request is a GET/HEAD/DELETE or a POST/PUT/PATCH request and make its best guess as to the type of parameter object it should generate. It will also generate the path parameters if your route contains them. Finally, this package will also scan any documentation you have in your action methods and add it as summary and description to that path, along with any appropriate annotations such as @deprecated.

One thing to note is this library leans on being explicit. It will choose to include keys even if they have a default. For example it chooses to say a route has a deprecated value of false rather than leaving it out. I believe this makes reading the documentation easier by not leaving important information out. The file can be easily cleaned up afterwards if the user chooses to leave out the defaults.

### Command line

[](#command-line)

Generating the swagger documentation is easy, simply run `php artisan swagger:generate` in your project root. The output of the command will be stored in your storage path linked in config file.

If you wish to generate docs for a subset of your routes, you can pass a filter using `--filter`, for example: `php artisan swagger:generate --filter="/api"`

You can also configure your swagger.php file to always generate schema when accessing Swagger UI or just by adding this line in your .env: `SWAGGER_GENERATE_ALWAYS=true`

By default, laravel-swagger prints out the documentation in json format, if you want it in YAML format you can override the format using the `--format` flag. Make sure to have the yaml extension installed if you choose to do so.

Format options are: `json``yaml`

### @Request() decorator

[](#request-decorator)

You can have only one `@Request()` decorator.

```
/**
* You can also do this, first line will be "summary"
*
* And anything 1 * apart from the "summary" will count as "description"
*
* @Request({
*     summary: Title of the route,
*     description: This is a longer description for the route which will be visible once the panel is expanded,
*     tags: Authentication,Users
* })
*/
public function someMethod(Request $request) {}
```

### @Response() decorator

[](#response-decorator)

You can have multiple `@Response` decorators

- The `code` property is required and must be the first in propery
- You can use the optional `description` property to desscribe your response
- You can use the optional `ref` property to refer a model, you can also wrap that model in \[\] to refer an array of that model or use the full model path inside, finally you can use a schema builder

```
/**
* @Response({
*     code: 200
*     description: return user model
*     ref: User
* })
* @Response({
*     code: 400
*     description: Bad Request, array of APIError model
*     ref: [APIError]
* })
* @Response({
*     code: 302
*     description: Redirect
* })
* @Response({
*     code: 500
*     description: Internal Server Error
* })
*/
public function someMethod(Request $request) {}

/**
 * You can also refer object directly
 *
 *
 * @Response({
 *     code: 200
 *     description: direct user model reference
 *     ref: #/components/schemas/User
 * })
 */
public function someMethod2(Request $request) {}

/**
 * Using P schema builder for Laravel Pagination
 *
 * @Response({
 *     code: 200
 *     description: a laravel pagination instance with User model
 *     ref: P(User)
 * })
 */
public function someMethod3(Request $request) {}
```

##### Note: You can see all available schema builder or create your own schema builder, explore swagger.schema\_builders config for more informations.

[](#note-you-can-see-all-available-schema-builder-or-create-your-own-schema-builder-explore-swaggerschema_builders-config-for-more-informations)

### Custom Validators

[](#custom-validators)

These validators are made purely for visual purposes, however, some of them can actually do validation

#### swagger\_default

[](#swagger_default)

```
$rules = [
    'locale'        =>  'swagger_default:en_GB'
];
```

#### swagger\_min

[](#swagger_min)

```
$rules = [
    'page'          =>  'swagger_default:1|swagger_min:1', // This will simply display the 'minimum' value in the documentation
    'page'          =>  'swagger_default:1|swagger_min:1:fail' // This will also fail if the `page` parameter will be less than 1
];
```

#### swagger\_max

[](#swagger_max)

```
$rules = [
    'take'          =>  'swagger_default:1|swagger_min:1|swagger_max:50', // This will simply display the 'maximum' value in the documentation
    'take'          =>  'swagger_default:1|swagger_min:1|swagger_max:50:fail' // This will also fail if the `take` parameter will be greater than 50
];
```

---

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance43

Moderate activity, may be stable

Popularity9

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 76.5% 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

Unknown

Total

1

Last Release

487d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4df8b5119bebeb027eaa90a5393bb6b8db879b2a41262952c448477346a181d6?d=identicon)[vanaboom](/maintainers/vanaboom)

---

Top Contributors

[![Mezatsong](https://avatars.githubusercontent.com/u/42788152?v=4)](https://github.com/Mezatsong "Mezatsong (26 commits)")[![aivaonair](https://avatars.githubusercontent.com/u/8265507?v=4)](https://github.com/aivaonair "aivaonair (3 commits)")[![MchMichael](https://avatars.githubusercontent.com/u/20338111?v=4)](https://github.com/MchMichael "MchMichael (2 commits)")[![Dainius-Dzialtuvas](https://avatars.githubusercontent.com/u/123356215?v=4)](https://github.com/Dainius-Dzialtuvas "Dainius-Dzialtuvas (1 commits)")[![evertramos](https://avatars.githubusercontent.com/u/905951?v=4)](https://github.com/evertramos "evertramos (1 commits)")[![kevincobain2000](https://avatars.githubusercontent.com/u/629055?v=4)](https://github.com/kevincobain2000 "kevincobain2000 (1 commits)")

---

Tags

laravelswaggergeneratordocs

### Embed Badge

![Health badge](/badges/vanaboom-laravel-swagger/health.svg)

```
[![Health](https://phpackages.com/badges/vanaboom-laravel-swagger/health.svg)](https://phpackages.com/packages/vanaboom-laravel-swagger)
```

###  Alternatives

[dingo/blueprint

API Blueprint documentation generator.

2707.8M22](/packages/dingo-blueprint)[infyomlabs/swagger-generator

Swagger Generator for InfyOm Laravel Generator

1151.1M5](/packages/infyomlabs-swagger-generator)[mezatsong/laravel-swagger-docs

Swagger docs generator for Laravel api

2457.4k](/packages/mezatsong-laravel-swagger-docs)[johnylemon/laravel-apidocs

Laravel API documentation generating tool

472.8k](/packages/johnylemon-laravel-apidocs)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)