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

ActiveLibrary[API Development](/categories/api)

doniyor6862/auto-swagger-laravel
================================

Automatically generate OpenAPI/Swagger documentation for Laravel applications using PHP attributes

1.0.3(1y ago)06MITPHPPHP ^8.0

Since Apr 5Pushed 1y ago1 watchersCompare

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

READMEChangelog (4)Dependencies (5)Versions (5)Used By (0)

 [![Swagger Logo](./public/img.png)](./public/img.png)

Laravel Auto Swagger
====================

[](#laravel-auto-swagger)

An automatic OpenAPI/Swagger documentation generator for Laravel applications inspired by NestJS's @nestjs/swagger package. This package uses PHP 8 attributes to annotate your controllers and models, while also automatically extracting information from your Laravel Form Requests and API Resources.

Features
--------

[](#features)

### Core Features

[](#core-features)

- ✅ Automatically generate OpenAPI 3.0 documentation from PHP 8 attributes
- ✅ Beautiful Swagger UI for browsing and testing your API
- ✅ Artisan command for generating documentation
- ✅ Custom route definition with middleware protection

### Smart Auto-Detection

[](#smart-auto-detection)

- ✅ **Automatic extraction of parameters from Laravel Form Request classes**
- ✅ **Automatic extraction of response schema from Laravel API Resources**
- ✅ **Custom API Resource schemas with the ApiResource attribute**
- ✅ **Documentation of Eloquent relationships in resources**
- ✅ **PHPDoc extraction from models (compatible with Laravel IDE Helper)**
- ✅ **Route analysis and selective documentation with ApiSwagger attribute**
- ✅ **Business exception documentation with ApiException attribute**
- ✅ Intelligent schema inference from models and type hints

### Documentation Features

[](#documentation-features)

- ✅ Support for documenting endpoints, parameters, request bodies, and responses
- ✅ Security scheme integration (JWT, OAuth, etc.)
- ✅ Customizable Swagger UI with theme options

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- Laravel 10.x
- Composer

Why Laravel Auto Swagger?
-------------------------

[](#why-laravel-auto-swagger)

Laravel Auto Swagger stands out from other documentation packages because:

1. **Zero Extra Work Mode** - If you're already using Laravel Form Requests, API Resources, or IDE Helper annotations, you get documentation for free with no additional work needed
2. **Multiple Documentation Styles** - Choose what works for you:

    - PHP 8 Attributes (similar to NestJS decorators)
    - Laravel Form Request validation rules
    - PHPDoc comments (compatible with Laravel IDE Helper)
    - API Resources for response schemas
3. **Laravel IDE Helper Compatible** - Reuse your existing Laravel IDE Helper PHPDoc annotations for generating API documentation
4. **Developer Experience First** - Designed to minimize the documentation burden while maximizing the quality of your API documentation

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

[](#installation)

Install the package via Composer:

```
composer require doniyor6862/auto-swagger-laravel
```

Publish the configuration file:

```
php artisan vendor:publish --tag=auto-swagger-config
```

Create the directory for your Swagger documentation:

```
mkdir -p public/swagger
```

Quick Start
-----------

[](#quick-start)

1. **Configure your API information** in `config/auto-swagger.php`
2. **Use Laravel Form Requests and API Resources** for your endpoints (automatic extraction)
3. **Generate documentation**: ```
    php artisan swagger:generate
    ```
4. **View your documentation** at `/api/documentation` (or your configured route)

Configuration
-------------

[](#configuration)

After publishing the configuration file, you can modify it at `config/auto-swagger.php`. Key configuration options include:

### Basic Information

[](#basic-information)

```
'title' => env('APP_NAME', 'Laravel') . ' API',
'description' => 'API Documentation',
'version' => '1.0.0',
```

### Output Settings

[](#output-settings)

```
'output_file' => public_path('swagger/swagger.json'),
'output_folder' => public_path('swagger'),
```

### Route Settings

[](#route-settings)

```
'route_prefix' => 'api/documentation',
'middleware' => [
    'web',
    // Add any additional middleware here (e.g., 'auth')
],
```

### Scanning Settings

[](#scanning-settings)

```
'scan' => [
    'controllers_path' => app_path('Http/Controllers'),
    'models_path' => app_path('Models'),
    'include_patterns' => [
        app_path('Http/Controllers/*.php'),
        app_path('Http/Controllers/**/*.php'),
    ],
    'exclude_patterns' => [],
    'use_phpdoc' => true, // Enable or disable PHPDoc scanning
],
```

### UI Settings

[](#ui-settings)

```
'ui' => [
    'enabled' => true,
    'theme' => 'default', // 'default', 'dark', 'light'
    'persist_authorization' => true,
    'display_request_duration' => true,
    'doc_expansion' => 'list', // 'list', 'full', 'none'
],
```

### Security Definitions

[](#security-definitions)

```
'securityDefinitions' => [
    'bearerAuth' => [
        'type' => 'http',
        'scheme' => 'bearer',
        'bearerFormat' => 'JWT',
    ],
],

'security' => [
    ['bearerAuth' => []],
],
```

Usage
-----

[](#usage)

Laravel Auto Swagger provides two ways to document your API:

1. **Zero-Config Mode**: Automatic extraction from Laravel Form Requests and API Resources
2. **Attribute Mode**: Explicit documentation using PHP 8 attributes

### Zero-Config Mode

[](#zero-config-mode)

Simply use standard Laravel practices and get documentation for free:

```