README

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

Installation

Install the package via Composer:

composer require auto-swagger/php-swagger-generator

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

To generate the OpenAPI documentation, run:

php artisan swagger:generate

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

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

3. Remove unused and Deleted controller usings namespaces

Attributes

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

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

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

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

Using an array:

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

Using an API Resource class:

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

Using a Model class:

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

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

To implement pagination in your API documentation:

Create a paginated resource class that extends PaginatedResource:

<?php
declare(strict_types=1);

namespace App\Http\Resources\User;

use AutoSwagger\Laravel\Resources\PaginatedResource;

class UserPaginatedResource extends PaginatedResource
{
    public function initCollection()
    {
        return $this->collection->map(function ($user) {
            return new UserResource($user);
        });
    }
}

Set isPagination to true in your ApiSwaggerResponse attribute:

#[ApiSwagger(summary: 'Get all users', tag: 'User')]
#[ApiSwaggerResponse(status: 200, resource: UserResource::class, isPagination: true)]
public function index(Request $request): UserPaginatedResource
{
    $users = $this->userRepository->paginate($request->input('perPage', 10));
    return new UserPaginatedResource($users);
}

For each reload on api/documentation route regenerate docs set environment:

SWAGGER_GENERATE_ALWAYS=true

Support

For support, feedback, or questions, contact the maintainer at: letenantdoniyor@gmail.com

auto-swagger / php-swagger-generator

Maintainers

Details