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

ActiveLibrary

zabaala/laravel-swagger-api
===========================

API Swagger UI package for Laravel. A fork of hcesrl/laravel-swagger-api

0307PHP

Since Aug 9Pushed 1y agoCompare

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

READMEChangelogDependenciesVersions (2)Used By (0)

zabaala/laravel-swagger-api
---------------------------

[](#zabaalalaravel-swagger-api)

[![License](https://camo.githubusercontent.com/30597ff9a350144f03bffdd9183e16468e0b3ca1193e1d08591d992622738d55/687474703a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://tldrlegal.com/license/mit-license)

Disclaimer
----------

[](#disclaimer)

This package is a fork of HCESrl/laravel-swagger-api, with some additional updates like as:

- Support to Laravel 9
- Support to PHP 7.4
- Support to response with Schemas

The Package
-----------

[](#the-package)

The packages adds a layer on top of the Laravel routing system allowing you to easily add metadata to your routes in order to create a [Swagger UI](https://swagger.io/tools/swagger-ui/) compliant API.

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Basic usage](#basic-usage)
    - [Configuration](#configuration)
    - [HTTPS/Trusted proxies](#httpstrusted-proxies)
    - [Routing](#routing)
    - [Route parameters](#route-parameters)
    - [Responses](#responses)
- [Advanced configuration](#advanced-configuration)
    - [General route parameters](#general-route-parameters)
    - [Guess parameters from FormRequest](#guess-parameters-from-formrequest)
    - [Tags](#tags)
    - [Versions](#versions)
    - [Aggregated resources endpoint](#aggregated-resources-endpoint)
    - [Aggregated models endpoint](#aggregated-models-endpoint)
    - [Authorization](#authorization)
    - [API Json Caching](#api-json-caching)
- [Todos](#todos)

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

[](#installation)

Install the package:

```
composer require hcesrl/laravel-swagger-api
```

Publish configuration and assets:

```
php artisan vendor:publish --provider="LaravelApi\ServiceProvider"
```

Basic usage
-----------

[](#basic-usage)

### Configuration

[](#configuration)

The main configuration is located in the `config/api.php` file. Here you can set some general metadata for your API specification such as the title, the description, etc.

Make sure that the `prefix` is the same used in your `RouteServiceProvider` for the api routes.

### HTTPS/Trusted proxies

[](#httpstrusted-proxies)

In case your API is hosted behind a load balancer and does not generate proper secure urls, refer to the Laravel docs about [configuring trusted proxies](https://laravel.com/docs/6.x/requests#configuring-trusted-proxies).

### Routing

[](#routing)

The `Api` facade works with the same syntax as the `Route` facade and you can use it directly in your `routes/api.php` file.

```
use LaravelApi\Facade as Api;

Api::get('some-uri', 'Controller@action');

Api::post('some-uri', function () {
    // do something
});
```

> **Note:** the supported methods: `get`, `post`, `put`, `delete`, `patch`, `options`. There's no support for the `match`method because every route must be associated with a single Operation in the Swagger specification.

When you create a new route, the Api facade returns an instance of an [Operation](https://swagger.io/specification/#tagObject)object. This object exposes some chainable configuration methods. The following example shows an extensive use of those methods.

```
use LaravelApi\Facade as Api;

Api::get('some-uri', 'Controller@action')
    ->setSummary('My operation summary')
    ->setDescription('My operation description')
    ->addTag('some-tag')
    ->setOperationId('executeAction')
    ->setConsumes(['application/json'])
    ->setProduces(['application/json']);
```

### Route parameters

[](#route-parameters)

You can define different types of route parameters after creating a route through the following methods:

- `addHeaderParameter`
- `addQueryParameter`
- `addPathParameter`
- `addFormDataParameter`
- `addBodyParameter`

All these methods accept 4 parameters: name, description, required and type:

```
use LaravelApi\Facade as Api;

Api::post('post-uri', 'Controller@action')
    ->addHeaderParameter('header-name', 'Some description.')
    ->addQueryParameter('query-name', 'Some description.', true, 'integer')
    ->addPathParameter('path-name', 'Some description.', true, 'string')
    ->addFormDataParameter('formdata-name', 'Some description.', true, 'string')
    ->addBodyParameter('param-name', 'Some description.', true);
```

> **Note:** the `addBodyParameter` method doesn't accept a `type` parameter, according to the Swagger specification.

If you need a deeper configuration for the parameter, you may pass a Closure function instead of a text description:

```
use LaravelApi\Facade as Api;

Api::post('post-uri-2', 'Controller@action')
    ->addQueryParameter('param-name', function($param) {
        $param->setDescription('Some param description')
              ->setType('integer')
              ->setFormat('int32');
    });
```

#### Route path parameter auto-parsing

[](#route-path-parameter-auto-parsing)

When you define a route containg path parameters using the [Laravel syntax](https://laravel.com/docs/5.5/routing#route-parameters), the route URI will be automatically parsed for path parameters, both required and optional.

The route:

```
use LaravelApi\Facade as Api;

Api::get('some-uri/{param1}/{param2?}', 'Controller@action');
```

will be parsed and the two path parameters will be added automatically. You can still edit the paramaters configuration:

```
use LaravelApi\Facade as Api;

Api::get('some-uri/{param1}/{param2?}', 'Controller@action')
   ->addPathParameter('param1', function( $param) {
       $param->setDescription('Some description');
   })
   ->addPathParameter('param2', 'Some other description.', false, 'integer');
```

It is also possible to disable the automatic route parsing from the main config file `config/api.php` setting `parse_route_parameters` to `false`.

#### Responses

[](#responses)

Use the `addResponse` to define the route response types:

```
use LaravelApi\Facade as Api;

$pet = Schema::create()
    ->addRequired('id')
    ->addRequired('name')

    ->setProperties(Properties::create()
        ->set('id', Schema::create()
            ->setType('integer')
            ->setFormat('int64')
        )
        ->set('name', Schema::create()
            ->setType('string')
        )
        ->set('tag', Schema::create()
            ->setType('string')
        )
    );

$error = Schema::create()
    ->addRequired('code')
    ->addRequired('message')

    ->setProperties(Properties::create()
        ->set('code', Schema::create()
            ->setType('integer')
            ->setFormat('int32')
        )
        ->set('error', Schema::create()
            ->setType('string')
        )
    );

Api::get('some-uri', 'Controller@action')
   ->addResponse(200, 'Successful operation', $pet)
   ->addResponse(422, 'Validation error', $error);
```

Advanced configuration
----------------------

[](#advanced-configuration)

### General route parameters

[](#general-route-parameters)

You may need to register different routes using the same parameters (eg. lang or locale) and these could lead to a long and difficult to maintein routes file.

To avoid this you can register general reusable route parameters that will be automatically applied when parameters with the same are found in the route uris.

```
use LaravelApi\Facade as Api;

Api::routeParameter('locale')
   ->setDescription('The request locale.')
   ->setRequired(true)
   ->addOptions('en', 'it');

Api::get('{locale}/some-uri', 'Controller@action');
```

### Guess parameters from FormRequest

[](#guess-parameters-from-formrequest)

In order to simplify the parameters registration, you may bind a Laravel [FormRequest](https://laravel.com/docs/5.5/validation#form-request-validation)directly to a route and let the package guess the parameters from the request rules.

```
use LaravelApi\Facade as Api;

Api::post('some-uri', 'Controller@action')
   ->bindRequest('App\\Http\\Requests\\MyFormRequest');
```

### Tags

[](#tags)

In order to create a [tag](https://swagger.io/specification/#tagObject) for your operations, you may call the `tag`method passing the name of the tag and its description, if needed.

You can also pass a callback function to create a group of operations automatically tagged with the given tag.

```
use LaravelApi\Facade as Api;

Api::tag('simple-tag');

Api::tag('tag-with-description', 'Tag description', function() {
    Api::get('tagged-uri', 'Controller@action');
});
```

You may register many tags at once by passing an array to the `tags` method:

```
use LaravelApi\Facade as Api;

Api::tags(
    [
        'tag_1' => 'Some tag description',
        'tag_2' => 'Some other tag description'
   ]
);
```

### Versions

[](#versions)

If you want to group your routes by different version, you may use the `version` method. The grouped routes will be automatically prefixed and tagged with the given version name.

```
use LaravelApi\Facade as Api;

/**
 * /api/v1/versioned-uri
 */
Api::version('v1', function () {
    Api::get('versioned-uri', 'Controller@action');
});

/**
 * /api/v2/versioned-uri
 */
Api::version('v2', function () {
    Api::get('versioned-uri', 'Controller@action');
});
```

### Aggregated resources endpoint

[](#aggregated-resources-endpoint)

An aggregate endpoint is an API endpoint that returns a mixed collection of resources, combining both Eloquent models and data generated by Closures.

```
use LaravelApi\Facade as Api;

Api::aggregate('aggregate/uri', [
    'App\\Page',
    'App\\Post',
    'settings' => function(SettingStore $settings) {
        return $settings->all();
    },
]);
```

> **Note:** closures require a non-numeric array key.

### Aggregated models endpoint

[](#aggregated-models-endpoint)

Building a complex API may require the creation of several endpoints exposing models data. You can easily do this with the `models` shortcut. With this method you can create a general resource endpoints connected to a simple Resource controller that implements only the `index` and `show` actions and handles multiple models.

The following configuration:

```
use LaravelApi\Facade as Api;

Api::models([
    'pages' => \App\Page::class,
    'users' => \App\User::class
]);
```

is equivalent to:

```
use LaravelApi\Facade as Api;

Api::resource('models/pages', 'SomeController')
   ->only('index', 'show');

Api::resource('models/users', 'SomeController')
   ->only('index', 'show');
```

#### Customize the response

[](#customize-the-response)

If you use custom [API Resources](https://laravel.com/docs/5.5/eloquent-resources) to personalize the API data you can define the following methods within your models in order the provide the right resource to the API server.

```
class Foo extends Model
{

    public function toApiResource($resource)
    {
        return new MyCustomResource($resource);
    }

    public function toApiResourceCollection($resource)
    {
        return new MyCustomResourceCollection($resource);
    }

}
```

### Authorization

[](#authorization)

In order to provide the security definitions for the specification you can use one the following methods:

```
use LaravelApi\Facade as Api;

Api::basicAuthSecurity('basic_auth');

Api::apiKeySecurity('api_key')
   ->parameterName('apiKey')
   ->inHeader();

Api::oauth2ImplicitSecurity('oauth2_implicit')
   ->authorizationUrl('http://www.foobar.com')
   ->description('A description for the auth.')
   ->setScopes([
       'write' => 'Write something',
       'read'  => 'Read something',
  ]);

Api::oauth2PasswordSecurity('oauth2_password')
   ->tokenUrl('http://www.foobar.com')
   ->setScopes(...);

Api::oauth2ApplicationSecurity('oauth2_application')
   ->tokenUrl('http://www.foobar.com')
   ->setScopes(...);

Api::oauth2AccessCodeSecurity('oauth2_accesscode')
   ->tokenUrl('http://www.foobar.com')
   ->setScopes(...);
```

In any operation you can set the required security schemes via the `requiresAuth` method:

```
Api::get('some-uri', 'Controller@action')
   ->requiresAuth('oauth2_implicit', ['read']);
```

and on resources as well:

```
Api::resource('models/pages', 'SomeController')
   ->requiresAuth('oauth2_implicit', ['read']);
```

### API Json Caching

[](#api-json-caching)

To generate a Swagger UI json file cache, just execute the `api:cache` Artisan command:

```
php artisan api:cache
```

After running this command, your cached json file will be used. Remember, if you add any new routes to the API you will need to generate a fresh route cache. Because of this, you should only run the `api:cache` command during your project's deployment.

You may use the `api:clear` command to clear the API cache:

```
php artisan api:clear
```

Todos
-----

[](#todos)

- Add support for [securityDefinitions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityDefinitionsObject);
- Add support for [Components](https://swagger.io/specification/#componentsObject);
- Add support for response [Examples](https://swagger.io/specification/#exampleObject);
- Implement authentication through [Laravel Passport](https://laravel.com/docs/5.5/passport);

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT).

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance27

Infrequent updates — may be unmaintained

Popularity15

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity27

Early-stage or recently created project

 Bus Factor1

Top contributor holds 93.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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/43bb7eab4b1fcac5055f49b8c171503be94442ebeb9aa4322bfeafe04e6f636c?d=identicon)[zabaala](/maintainers/zabaala)

---

Top Contributors

[![fsavina](https://avatars.githubusercontent.com/u/4038144?v=4)](https://github.com/fsavina "fsavina (101 commits)")[![zabaala](https://avatars.githubusercontent.com/u/4934492?v=4)](https://github.com/zabaala "zabaala (5 commits)")[![edin](https://avatars.githubusercontent.com/u/572400?v=4)](https://github.com/edin "edin (1 commits)")[![lloricode](https://avatars.githubusercontent.com/u/8251344?v=4)](https://github.com/lloricode "lloricode (1 commits)")

### Embed Badge

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

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

PHPackages © 2026

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