Laravel API Toolkit

stackmasteraliza/laravel-api-response

Features

Installation

composer require stackmasteraliza/laravel-api-response

Publish Configuration (Optional)

php artisan vendor:publish --tag=api-response-config

Usage

Using the Facade

useStackmasteraliza\ApiResponse\Facades\ApiResponse;// Success responsereturn ApiResponse::success($data,'Data retrieved successfully');// Error responsereturn ApiResponse::error('Something went wrong',400);// Created response (201)return ApiResponse::created($user,'User created successfully');// Not found response (404)return ApiResponse::notFound('User not found');// Validation error response (422)return ApiResponse::validationError(['email' => ['The email field is required.'],'name' => ['The name field is required.'],]);

Using the Trait

useStackmasteraliza\ApiResponse\Traits\HasApiResponse;class UserControllerextends Controller{use HasApiResponse;publicfunctionindex()    {$users = User::paginate(15);return$this->success($users,'Users retrieved successfully');    }publicfunctionstore(Request$request)    {$user = User::create($request->validated());return$this->created($user,'User created successfully');    }publicfunctionshow(User$user)    {return$this->success($user);    }publicfunctiondestroy(User$user)    {$user->delete();return$this->noContent();    }}

Available Methods

Success Responses

Error Responses

Response Structure

Success Response

{"status_code":200,"success":true,"message":"Data retrieved successfully","data": {"id":1,"name":"John Doe","email":"john@example.com"    }}

Paginated Response

{"status_code":200,"success":true,"message":"Users retrieved successfully","data": [        {"id":1,"name":"John Doe"},        {"id":2,"name":"Jane Doe"}    ],"meta": {"current_page":1,"per_page":15,"total":50,"last_page":4,"from":1,"to":15,"path":"http://example.com/api/users","links": {"first":"http://example.com/api/users?page=1","last":"http://example.com/api/users?page=4","prev":null,"next":"http://example.com/api/users?page=2"        }    }}

Cursor Paginated Response

$users = User::cursorPaginate(15);return ApiResponse::success($users,'Users retrieved successfully');

{"status_code":200,"success":true,"message":"Users retrieved successfully","data": [        {"id":1,"name":"John Doe"},        {"id":2,"name":"Jane Doe"}    ],"meta": {"per_page":15,"next_cursor":"eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0","prev_cursor":null,"path":"http://example.com/api/users","links": {"next":"http://example.com/api/users?cursor=eyJpZCI6MTUuLi4","prev":null        }    }}

Error Response

{"status_code":422,"success":false,"message":"Validation failed","errors": {"email": ["The email field is required."],"name": ["The name field is required."]    }}

Exception Handling

useStackmasteraliza\ApiResponse\Exceptions\ApiExceptionHandler;->withExceptions(function (Exceptions$exceptions) {$exceptions->render(function (Throwable$e,Request$request) {$handler =newApiExceptionHandler();return$handler->handle($e,$request);    });})

useStackmasteraliza\ApiResponse\Exceptions\ApiExceptionHandler;publicfunctionrender($request,Throwable$exception){$handler =newApiExceptionHandler();$response =$handler->handle($exception,$request);if ($response) {return$response;    }returnparent::render($request,$exception);}

Middleware

// In your route file or middleware groupuseStackmasteraliza\ApiResponse\Http\Middleware\ForceJsonResponse;Route::middleware([ForceJsonResponse::class])->group(function () {// Your API routes});

Adding Custom Data

return ApiResponse::success($user)    ->withData('token',$token)    ->withHeader('X-Custom-Header','value');

Response Macros

// In your AppServiceProvider boot() methoduseStackmasteraliza\ApiResponse\Facades\ApiResponse;ApiResponse::macro('banned',function (string$reason ='Account suspended') {return$this->error($reason,403);});ApiResponse::macro('maintenance',function () {return$this->error('Service under maintenance',503);});

return ApiResponse::banned('Your account has been suspended');return ApiResponse::maintenance();

Testing Helpers

useTests\TestCase;class UserControllerTestextends TestCase{publicfunctiontest_can_list_users()    {$response =$this->getJson('/api/users');$response->assertApiSuccess()                 ->assertApiStatusCode(200)                 ->assertApiMessage('Users retrieved successfully')                 ->assertApiHasData()                 ->assertApiPaginated();    }publicfunctiontest_validation_errors()    {$response =$this->postJson('/api/users', []);$response->assertApiError(422)                 ->assertApiMessage('Validation failed')                 ->assertApiHasErrors('email');    }publicfunctiontest_user_data()    {$response =$this->getJson('/api/users/1');$response->assertApiSuccess()                 ->assertApiDataContains(['id' =>1,'name' =>'John Doe']);    }}

Available Test Assertions

OpenAPI/Swagger Documentation

Export to Multiple Formats

Built-in Authorization

WebSocket Tester

Zero-Configuration Auto-Generation

View Documentation

http://your-app.com/api-docs

Custom Swagger UI Features

Export API Documentation

OpenAPI Specification

API Client Collections

Customization

# App brandingAPI_DOCS_APP_NAME=My Awesome APIAPI_DOCS_APP_LOGO=https://example.com/logo.png# Theme color (default: #10b981 - green)API_DOCS_THEME_COLOR=#10b981# Default theme: dark, light, or auto (default: auto)API_DOCS_DEFAULT_THEME=auto# Enable/disable documentationAPI_DOCS_ENABLED=true

// config/api-response.php'openapi' => ['enabled' =>env('API_DOCS_ENABLED',true),'title' =>env('API_DOCS_TITLE','API Documentation'),'description' =>'Auto-generated API documentation','version' =>'1.0.0','route_prefix' =>'api','docs_route' =>'api-docs',// Custom branding'app_name' =>env('API_DOCS_APP_NAME',env('APP_NAME','API')),'app_logo' =>env('API_DOCS_APP_LOGO',null),'theme_color' =>env('API_DOCS_THEME_COLOR','#10b981'),'default_theme' =>env('API_DOCS_DEFAULT_THEME','auto'),// dark, light, auto'servers' => [        ['url' =>env('APP_URL'),'description' =>'API Server'],    ],],

API Endpoints

Generate Static File

php artisan api:docs

Enhanced Documentation with Attributes (Optional)

useStackmasteraliza\ApiResponse\Attributes\ApiEndpoint;useStackmasteraliza\ApiResponse\Attributes\ApiRequest;useStackmasteraliza\ApiResponse\Attributes\ApiRequestBody;useStackmasteraliza\ApiResponse\Attributes\ApiResponse;class UserControllerextends Controller{    #[ApiEndpoint(        summary:'List all users',        description:'Retrieve a paginated list of all users in the system',        tags: ['Users']    )]    #[ApiRequest(name:'page', type:'integer', in:'query', description:'Page number')]    #[ApiRequest(name:'per_page', type:'integer', in:'query', description:'Items per page')]    #[ApiResponse(status:200, description:'Users retrieved successfully', ref:'PaginatedResponse')]publicfunctionindex():JsonResponse    {return ApiResponse::success(User::paginate(15));    }    #[ApiEndpoint(        summary:'Create a new user',        description:'Create a new user in the system',        tags: ['Users']    )]    #[ApiRequestBody(        properties: ['name' =>'string','email' =>'string','password' =>'string'],        required: ['name','email','password'],        example: ['name' =>'John Doe','email' =>'john@example.com','password' =>'secret']    )]    #[ApiResponse(status:201, description:'User created successfully')]    #[ApiResponse(status:422, description:'Validation error', ref:'ValidationErrorResponse')]publicfunctionstore(Request$request):JsonResponse    {$user = User::create($request->validated());return ApiResponse::created($user);    }}

Available Attributes

Built-in Schema References

Configuration

return [// Default messages'default_success_message' =>'Success','default_error_message' =>'Error',// Include debug info in error responses (when APP_DEBUG=true)'include_debug_info' =>env('API_RESPONSE_DEBUG',false),// Include HTTP status code in response body'include_status_code' =>env('API_RESPONSE_INCLUDE_STATUS_CODE',true),// Customize response keys'keys' => ['success' =>'success','message' =>'message','data' =>'data','errors' =>'errors','meta' =>'meta','status_code' =>'status_code',    ],];

Disabling Status Code in Response Body

API_RESPONSE_INCLUDE_STATUS_CODE=false

'include_status_code' => false,

API Versioning

Enable Versioning

API_DOCS_VERSIONING=true

'openapi' => [// ... other options'versioning' => ['enabled' =>true,'auto_detect' =>true,'default_version' =>'v2',// Optional: set default version    ],],

Custom Version Definitions

'versioning' => ['enabled' =>true,'auto_detect' =>false,'default_version' =>'v2','versions' => ['v1' => ['title' =>'API v1 (Legacy)','description' =>'Legacy API version - deprecated','pattern' =>'api/v1/*',        ],'v2' => ['title' =>'API v2 (Current)','description' =>'Current stable API version','pattern' =>'api/v2/*',        ],    ],],

Versioned Endpoints

WebSocket Testing

Features

Configuration

'openapi' => ['websocket' => ['enabled' =>true,'url' =>env('WEBSOCKET_URL','ws://localhost:6001'),'endpoints' => [],    ],],

Testing

composertest

Contributing

License