PHPackages                             auto-swagger/php-swagger-generator - 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. auto-swagger/php-swagger-generator

ActiveLibrary[API Development](/categories/api)

auto-swagger/php-swagger-generator
==================================

Automatic Swagger/OpenAPI documentation generator using PHP attributes

13.5(1y ago)21.1k↓40.7%2MITPHPPHP ^8.2

Since Dec 3Pushed 1y ago1 watchersCompare

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

READMEChangelog (10)Dependencies (4)Versions (19)Used By (0)

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

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

Auto Swagger for Laravel is a package that helps you generate Swagger/OpenAPI 1.0 documentation quickly and easily for your Laravel applications.

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

[](#installation)

1. Install the package via Composer:

```
composer require auto-swagger/php-swagger-generator
```

2. Publish the necessary files:

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

# Views (optional)
php artisan vendor:publish --tag=auto-swagger-views

# Assets (optional)
php artisan vendor:publish --tag=auto-swagger-assets
```

Generating Documentation
------------------------

[](#generating-documentation)

To generate the OpenAPI documentation, run:

```
php artisan swagger:generate
```

### Output Format Options

[](#output-format-options)

The generator supports both JSON and YAML formats:

- Generate JSON (default):

```
php artisan swagger:generate --format=json
```

- Generate YAML:

```
php artisan swagger:generate --format=yaml
```

When using the default JSON format, the documentation will be accessible at: `http://localhost:8000/api/documentation/json`

1. All attributes must be written in controller
===============================================

[](#1-all-attributes-must-be-written-in-controller)

2. If you are using resource controller write apiResource instead resource
==========================================================================

[](#2-if-you-are-using-resource-controller-write-apiresource-instead-resource)

3. Remove unused and Deleted controller usings namespaces
=========================================================

[](#3-remove-unused-and-deleted-controller-usings-namespaces)

Attributes
----------

[](#attributes)

### Route Documentation

[](#route-documentation)

To include a route in the API documentation, use the `ApiSwagger` attribute:

```
#[ApiSwagger(summary: 'Store user', tag: 'User')]
```

Properties:

- `summary`: Description of the route
- `tag`: Group identifier for related routes

### Request Documentation

[](#request-documentation)

Document request parameters using `ApiSwaggerRequest`:

On the controller method you need use Request class for validation, if you does not do this AutoSwager will not parse RequestBody

```
#[ApiSwaggerRequest(request: UserCreateRequest::class, description: 'Store user')]
public function store(UserCreateRequest $request): UserPaginatedResource
{
    // some Logic
}
```

### Query Parameters

[](#query-parameters)

Use `ApiSwaggerQuery` to define filter parameters for your API endpoints:

```
#[ApiSwaggerQuery([
name: "name",
description: "Search by user name",
required: false
])]
```

if you need paste id Of model you need make isId parameter true

```
#[ApiSwaggerQuery(name: "id", required: true, isId: true)]
```

The format for each query parameter is: `'parameter_name' => 'type|required/optional|description'`

Supported types:

- string
- integer
- boolean
- date
- array
- float

Example of a complete endpoint with query parameters:

```
#[ApiSwagger(summary: 'List users', tag: 'User')]
#[ApiSwaggerQuery([
name: "search",
description: "Search by name or email",
required: false
])]
#[ApiSwaggerQuery([
name: "status",
description: "Filter by user status",
required: false
])]
#[ApiSwaggerResponse(status: 200, resource: UserResource::class, isPagination: true)]
public function index(Request $request): UserPaginatedResource
{
    $users = $this->userRepository
        ->filter($request->all())
        ->paginate($request->input('perPage', 10));

    return new UserPaginatedResource($users);
}
```

### Response Documentation

[](#response-documentation)

Document API responses using `ApiSwaggerResponse`. You can specify the response structure in three ways:

1. Using an array:

```
#[ApiSwaggerResponse(status: 200, resource: [
    'id' => 'integer',
    'name' => 'string',
    'email' => 'string',
])]
```

2. Using an API Resource class:

```
#[ApiSwaggerResponse(status: 200, resource: ApiResource::class, description: 'User details')]
```

3. Using a Model class:

```
#[ApiSwaggerResponse(status: 200, resource: Model::class, description: 'User details')]
```

Resource class
--------------

[](#resource-class)

```
use AutoSwagger\Attributes\ApiSwaggerResource;
use Illuminate\Http\Resources\Json\JsonResource;

#[ApiSwaggerResource(name: 'User', properties: [
    'id' => 'integer',
    'name' => 'string',
])]
class ApiResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'name' => $this->name,
            'id' => $this->id
        ];
    }
}
```

Pagination Support
------------------

[](#pagination-support)

To implement pagination in your API documentation:

1. Create a paginated resource class that extends `PaginatedResource`:

```